1
0
mirror of https://github.com/postgres/postgres.git synced 2025-07-27 12:41:57 +03:00

Two-phase commit. Original patch by Heikki Linnakangas, with additional

hacking by Alvaro Herrera and Tom Lane.
This commit is contained in:
Tom Lane
2005-06-17 22:32:51 +00:00
parent 5495575903
commit d0a89683a3
61 changed files with 4454 additions and 439 deletions

View File

@ -1,6 +1,6 @@
<!--
Documentation of the system catalogs, directed toward PostgreSQL developers
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.103 2005/06/13 23:14:47 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/catalogs.sgml,v 2.104 2005/06/17 22:32:41 tgl Exp $
-->
<chapter id="catalogs">
@ -3932,6 +3932,11 @@
<entry>currently held locks</entry>
</row>
<row>
<entry><link linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link></entry>
<entry>currently prepared transactions</entry>
</row>
<row>
<entry><link linkend="view-pg-rules"><structname>pg_rules</structname></link></entry>
<entry>rules</entry>
@ -4167,8 +4172,10 @@
<entry><structfield>pid</structfield></entry>
<entry><type>integer</type></entry>
<entry></entry>
<entry>process ID of the server process holding or awaiting this
lock</entry>
<entry>
Process ID of the server process holding or awaiting this
lock. Zero if the lock is held by a prepared transaction.
</entry>
</row>
<row>
<entry><structfield>mode</structfield></entry>
@ -4250,6 +4257,87 @@
</sect1>
<sect1 id="view-pg-prepared-xacts">
<title><structname>pg_prepared_xacts</structname></title>
<indexterm zone="view-pg-prepared-xacts">
<primary>pg_prepared_xacts</primary>
</indexterm>
<para>
The view <structname>pg_prepared_xacts</structname> displays
information about transactions that are currently prepared for two-phase
commit (see <xref linkend="sql-prepare-transaction"
endterm="sql-prepare-transaction-title"> for details).
</para>
<para>
<structname>pg_prepared_xacts</structname> contains one row per prepared
transaction. An entry is removed when the transaction is committed or
rolled back.
</para>
<table>
<title><structname>pg_prepared_xacts</> Columns</title>
<tgroup cols=4>
<thead>
<row>
<entry>Name</entry>
<entry>Type</entry>
<entry>References</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><structfield>transaction</structfield></entry>
<entry><type>xid</type></entry>
<entry></entry>
<entry>
Numeric transaction identifier of the prepared transaction
</entry>
</row>
<row>
<entry><structfield>gid</structfield></entry>
<entry><type>text</type></entry>
<entry></entry>
<entry>
Global transaction identifier that was assigned to the transaction
</entry>
</row>
<row>
<entry><structfield>owner</structfield></entry>
<entry><type>name</type></entry>
<entry><literal><link linkend="catalog-pg-shadow"><structname>pg_shadow</structname></link>.usename</literal></entry>
<entry>
Name of the user that executed the transaction
</entry>
</row>
<row>
<entry><structfield>database</structfield></entry>
<entry><type>name</type></entry>
<entry><literal><link linkend="catalog-pg-database"><structname>pg_database</structname></link>.datname</literal></entry>
<entry>
Name of the database in which the transaction was executed
</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
When the <structname>pg_prepared_xacts</structname> view is accessed, the
internal transaction manager data structures are momentarily locked, and
a copy is made for the view to display. This ensures that the
view produces a consistent set of results, while not blocking
normal operations longer than necessary. Nonetheless
there could be some impact on database performance if this view is
read often.
</para>
</sect1>
<sect1 id="view-pg-rules">
<title><structname>pg_rules</structname></title>

View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.62 2004/08/21 16:16:04 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.63 2005/06/17 22:32:42 tgl Exp $
PostgreSQL documentation
Complete list of usable sgml source files in this directory.
-->
@ -30,6 +30,7 @@ Complete list of usable sgml source files in this directory.
<!entity cluster system "cluster.sgml">
<!entity commentOn system "comment.sgml">
<!entity commit system "commit.sgml">
<!entity commitPrepared system "commit_prepared.sgml">
<!entity copyTable system "copy.sgml">
<!entity createAggregate system "create_aggregate.sgml">
<!entity createCast system "create_cast.sgml">
@ -88,11 +89,13 @@ Complete list of usable sgml source files in this directory.
<!entity move system "move.sgml">
<!entity notify system "notify.sgml">
<!entity prepare system "prepare.sgml">
<!entity prepareTransaction system "prepare_transaction.sgml">
<!entity reindex system "reindex.sgml">
<!entity releaseSavepoint system "release_savepoint.sgml">
<!entity reset system "reset.sgml">
<!entity revoke system "revoke.sgml">
<!entity rollback system "rollback.sgml">
<!entity rollbackPrepared system "rollback_prepared.sgml">
<!entity rollbackTo system "rollback_to.sgml">
<!entity savepoint system "savepoint.sgml">
<!entity select system "select.sgml">

View File

@ -0,0 +1,111 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/commit_prepared.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-COMMIT-PREPARED">
<refmeta>
<refentrytitle id="sql-commit-prepared-title">COMMIT PREPARED</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>COMMIT PREPARED</refname>
<refpurpose>commit a transaction that was earlier prepared for two-phase commit</refpurpose>
</refnamediv>
<indexterm zone="sql-commit-prepared">
<primary>COMMIT PREPARED</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
COMMIT PREPARED <replaceable class="PARAMETER">transaction_id</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>COMMIT PREPARED</command> commits a transaction that is in
prepared state.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">transaction_id</replaceable></term>
<listitem>
<para>
The transaction identifier of the transaction that is to be
committed.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
To commit a prepared transaction, you must be either the same user that
executed the transaction originally, or a superuser. But you do not
have to be in the same session that executed the transaction.
</para>
<para>
This command cannot be executed inside a transaction block. The prepared
transaction is committed immediately.
</para>
<para>
All currently available prepared transactions are listed in the
<structname>pg_prepared_xacts</> system view.
</para>
</refsect1>
<refsect1 id="sql-commit-prepared-examples">
<title id="sql-commit-prepared-examples-title">Examples</title>
<para>
Commit the transaction identified by the transaction
identifier <literal>foobar</>:
<programlisting>
COMMIT PREPARED 'foobar';
</programlisting>
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-prepare-transaction" endterm="sql-prepare-transaction-title"></member>
<member><xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

View File

@ -0,0 +1,160 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-PREPARE-TRANSACTION">
<refmeta>
<refentrytitle id="sql-prepare-transaction-title">PREPARE TRANSACTION</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>PREPARE TRANSACTION</refname>
<refpurpose>prepare the current transaction for two-phase commit</refpurpose>
</refnamediv>
<indexterm zone="sql-prepare-transaction">
<primary>PREPARE TRANSACTION</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
PREPARE TRANSACTION <replaceable class="PARAMETER">transaction_id</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>PREPARE TRANSACTION</command> prepares the current transaction
for two-phase commit. After this command, the transaction is no longer
associated with the current session; instead, its state is fully stored on
disk, and there is a very high probability that it can be committed
successfully, even if a database crash occurs before the commit is
requested.
</para>
<para>
Once prepared, a transaction can later be committed or rolled
back with <command>COMMIT PREPARED</command> or
<command>ROLLBACK PREPARED</command>, respectively. Those commands
can be issued from any session, not only the one that executed the
original transaction.
</para>
<para>
From the point of view of the issuing session, <command>PREPARE
TRANSACTION</command> is not unlike a <command>ROLLBACK</> command:
after executing it, there is no active current transaction, and the
effects of the prepared transaction are no longer visible. (The effects
will become visible again if the transaction is committed.)
</para>
<para>
If the <command>PREPARE TRANSACTION</command> command fails for any
reason, it becomes a <command>ROLLBACK</>: the current transaction
is canceled.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">transaction_id</replaceable></term>
<listitem>
<para>
An arbitrary identifier that later identifies this transaction for
<command>COMMIT PREPARED</> or <command>ROLLBACK PREPARED</>.
The identifier must be written as a string literal, and must be
less than 200 bytes long. It must not be the same as the identifier
used for any currently prepared transaction.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
This command must be used inside a transaction block. Use
<command>BEGIN</command> to start one.
</para>
<para>
It is not currently allowed to <command>PREPARE</> a transaction that
has executed any operations involving temporary tables nor
created any cursors <literal>WITH HOLD</>. Those features are too tightly
tied to the current session to be useful in a transaction to be prepared.
</para>
<para>
If the transaction modified any run-time parameters with <command>SET</>,
those effects persist after <command>PREPARE TRANSACTION</>, and will not
be affected by any later <command>COMMIT PREPARED</command> or
<command>ROLLBACK PREPARED</command>. Thus, in this one respect
<command>PREPARE TRANSACTION</> acts more like <command>COMMIT</> than
<command>ROLLBACK</>.
</para>
<para>
All currently available prepared transactions are listed in the
<structname>pg_prepared_xacts</> system view.
</para>
<para>
From a performance standpoint, it is unwise to leave transactions in
the prepared state for a long time: this will for instance interfere with
the ability of <command>VACUUM</> to reclaim storage. Keep in mind also
that the transaction continues to hold whatever locks it held.
The intended
usage of the feature is that a prepared transaction will normally be
committed or rolled back as soon as an external transaction manager
has verified that other databases are also prepared to commit.
</para>
</refsect1>
<refsect1 id="sql-prepare-transaction-examples">
<title id="sql-prepare-transaction-examples-title">Examples</title>
<para>
Prepare the current transaction for two-phase commit, using
<literal>foobar</> as the transaction identifier:
<programlisting>
PREPARE TRANSACTION 'foobar';
</programlisting>
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title"></member>
<member><xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

View File

@ -0,0 +1,111 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/rollback_prepared.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-ROLLBACK-PREPARED">
<refmeta>
<refentrytitle id="sql-rollback-prepared-title">ROLLBACK PREPARED</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ROLLBACK PREPARED</refname>
<refpurpose>cancel a transaction that was earlier prepared for two-phase commit</refpurpose>
</refnamediv>
<indexterm zone="sql-rollback-prepared">
<primary>ROLLBACK PREPARED</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
ROLLBACK PREPARED <replaceable class="PARAMETER">transaction_id</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>ROLLBACK PREPARED</command> rolls back a transaction that is in
prepared state.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">transaction_id</replaceable></term>
<listitem>
<para>
The transaction identifier of the transaction that is to be
rolled back.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
To roll back a prepared transaction, you must be either the same user that
executed the transaction originally, or a superuser. But you do not
have to be in the same session that executed the transaction.
</para>
<para>
This command cannot be executed inside a transaction block. The prepared
transaction is rolled back immediately.
</para>
<para>
All currently available prepared transactions are listed in the
<structname>pg_prepared_xacts</> system view.
</para>
</refsect1>
<refsect1 id="sql-rollback-prepared-examples">
<title id="sql-rollback-prepared-examples-title">Examples</title>
<para>
Roll back the transaction identified by the transaction
identifier <literal>foobar</>:
<programlisting>
ROLLBACK PREPARED 'foobar';
</programlisting>
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-prepare-transaction" endterm="sql-prepare-transaction-title"></member>
<member><xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

View File

@ -1,5 +1,5 @@
<!-- reference.sgml
$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.52 2004/08/21 16:16:03 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.53 2005/06/17 22:32:42 tgl Exp $
PostgreSQL Reference Manual
-->
@ -62,6 +62,7 @@ PostgreSQL Reference Manual
&cluster;
&commentOn;
&commit;
&commitPrepared;
&copyTable;
&createAggregate;
&createCast;
@ -120,11 +121,13 @@ PostgreSQL Reference Manual
&move;
&notify;
&prepare;
&prepareTransaction;
&reindex;
&releaseSavepoint;
&reset;
&revoke;
&rollback;
&rollbackPrepared;
&rollbackTo;
&savepoint;
&select;

View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.328 2005/06/17 13:12:01 momjian Exp $
$PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.329 2005/06/17 22:32:42 tgl Exp $
-->
<chapter Id="runtime">
@ -956,7 +956,7 @@ SET ENABLE_SEQSCAN TO OFF;
<para>
Sets the location of the Kerberos server key file. See
<xref linkend="kerberos-auth"> for details. This parameter
can only be set at server start.
can only be set at server start.
</para>
</listitem>
</varlistentry>
@ -1113,6 +1113,33 @@ SET ENABLE_SEQSCAN TO OFF;
</listitem>
</varlistentry>
<varlistentry id="guc-max-prepared-transactions" xreflabel="max_prepared_transactions">
<term><varname>max_prepared_transactions</varname> (<type>integer</type>)</term>
<indexterm>
<primary><varname>max_prepared_transactions</> configuration parameter</primary>
</indexterm>
<listitem>
<para>
Sets the maximum number of transactions that can be in the
<quote>prepared</> state simultaneously (see <xref
linkend="sql-prepare-transaction"
endterm="sql-prepare-transaction-title">).
Setting this parameter to zero disables the prepared-transaction
feature.
The default is 50.
This option can only be set at server start.
</para>
<para>
Increasing this parameter may cause <productname>PostgreSQL</>
to request more <systemitem class="osname">System V</> shared
memory than your operating system's default configuration
allows. See <xref linkend="sysvipc"> for information on how to
adjust those parameters, if necessary.
</para>
</listitem>
</varlistentry>
<varlistentry id="guc-work-mem" xreflabel="work_mem">
<term><varname>work_mem</varname> (<type>integer</type>)</term>
<indexterm>