diff options
Diffstat (limited to 'doc/src/sgml/ref/prepare_transaction.sgml')
| -rw-r--r-- | doc/src/sgml/ref/prepare_transaction.sgml | 181 |
1 files changed, 181 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/prepare_transaction.sgml b/doc/src/sgml/ref/prepare_transaction.sgml new file mode 100644 index 0000000..f4f6118 --- /dev/null +++ b/doc/src/sgml/ref/prepare_transaction.sgml @@ -0,0 +1,181 @@ +<!-- +doc/src/sgml/ref/prepare_transaction.sgml +PostgreSQL documentation +--> + +<refentry id="sql-prepare-transaction"> + <indexterm zone="sql-prepare-transaction"> + <primary>PREPARE TRANSACTION</primary> + </indexterm> + + <refmeta> + <refentrytitle>PREPARE TRANSACTION</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>PREPARE TRANSACTION</refname> + <refpurpose>prepare the current transaction for two-phase commit</refpurpose> + </refnamediv> + + <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 <link linkend="sql-commit-prepared"><command>COMMIT PREPARED</command></link> + or <link linkend="sql-rollback-prepared"><command>ROLLBACK PREPARED</command></link>, + 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> 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</command>: 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</command> or <command>ROLLBACK PREPARED</command>. + 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> + <command>PREPARE TRANSACTION</command> is not intended for use in applications + or interactive sessions. Its purpose is to allow an external + transaction manager to perform atomic global transactions across multiple + databases or other transactional resources. Unless you're writing a + transaction manager, you probably shouldn't be using <command>PREPARE + TRANSACTION</command>. + </para> + + <para> + This command must be used inside a transaction block. Use <link + linkend="sql-begin"><command>BEGIN</command></link> to start one. + </para> + + <para> + It is not currently allowed to <command>PREPARE</command> a transaction that + has executed any operations involving temporary tables or the session's + temporary namespace, created any cursors <literal>WITH HOLD</literal>, or + executed <command>LISTEN</command>, <command>UNLISTEN</command>, or + <command>NOTIFY</command>. + 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</command> + (without the <literal>LOCAL</literal> option), + those effects persist after <command>PREPARE TRANSACTION</command>, 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</command> acts more like <command>COMMIT</command> than + <command>ROLLBACK</command>. + </para> + + <para> + All currently available prepared transactions are listed in the + <link linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link> + system view. + </para> + + <caution> + <para> + It is unwise to leave transactions in the prepared state for a long time. + This will interfere with the ability of <command>VACUUM</command> to reclaim + storage, and in extreme cases could cause the database to shut down + to prevent transaction ID wraparound (see <xref + linkend="vacuum-for-wraparound"/>). 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> + + <para> + If you have not set up an external transaction manager to track prepared + transactions and ensure they get closed out promptly, it is best to keep + the prepared-transaction feature disabled by setting + <xref linkend="guc-max-prepared-transactions"/> to zero. This will + prevent accidental creation of prepared transactions that might then + be forgotten and eventually cause problems. + </para> + </caution> + </refsect1> + + <refsect1 id="sql-prepare-transaction-examples"> + <title>Examples</title> + <para> + Prepare the current transaction for two-phase commit, using + <literal>foobar</literal> as the transaction identifier: + +<programlisting> +PREPARE TRANSACTION 'foobar'; +</programlisting></para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>PREPARE TRANSACTION</command> is a + <productname>PostgreSQL</productname> extension. It is intended for use by + external transaction management systems, some of which are covered by + standards (such as X/Open XA), but the SQL side of those systems is not + standardized. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-commit-prepared"/></member> + <member><xref linkend="sql-rollback-prepared"/></member> + </simplelist> + </refsect1> + +</refentry> |