diff options
Diffstat (limited to 'doc/src/sgml/html/sql-prepare-transaction.html')
| -rw-r--r-- | doc/src/sgml/html/sql-prepare-transaction.html | 90 |
1 files changed, 90 insertions, 0 deletions
diff --git a/doc/src/sgml/html/sql-prepare-transaction.html b/doc/src/sgml/html/sql-prepare-transaction.html new file mode 100644 index 0000000..289d007 --- /dev/null +++ b/doc/src/sgml/html/sql-prepare-transaction.html @@ -0,0 +1,90 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PREPARE TRANSACTION</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-prepare.html" title="PREPARE" /><link rel="next" href="sql-reassign-owned.html" title="REASSIGN OWNED" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">PREPARE TRANSACTION</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-prepare.html" title="PREPARE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-reassign-owned.html" title="REASSIGN OWNED">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-PREPARE-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.160.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">PREPARE TRANSACTION</span></h2><p>PREPARE TRANSACTION — prepare the current transaction for two-phase commit</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis"> +PREPARE TRANSACTION <em class="replaceable"><code>transaction_id</code></em> +</pre></div><div class="refsect1" id="id-1.9.3.160.5"><h2>Description</h2><p> + <code class="command">PREPARE TRANSACTION</code> 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. + </p><p> + Once prepared, a transaction can later be committed or rolled back + with <a class="link" href="sql-commit-prepared.html" title="COMMIT PREPARED"><code class="command">COMMIT PREPARED</code></a> + or <a class="link" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED"><code class="command">ROLLBACK PREPARED</code></a>, + respectively. Those commands can be issued from any session, not + only the one that executed the original transaction. + </p><p> + From the point of view of the issuing session, <code class="command">PREPARE + TRANSACTION</code> is not unlike a <code class="command">ROLLBACK</code> 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.) + </p><p> + If the <code class="command">PREPARE TRANSACTION</code> command fails for any + reason, it becomes a <code class="command">ROLLBACK</code>: the current transaction + is canceled. + </p></div><div class="refsect1" id="id-1.9.3.160.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>transaction_id</code></em></span></dt><dd><p> + An arbitrary identifier that later identifies this transaction for + <code class="command">COMMIT PREPARED</code> or <code class="command">ROLLBACK PREPARED</code>. + 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. + </p></dd></dl></div></div><div class="refsect1" id="id-1.9.3.160.7"><h2>Notes</h2><p> + <code class="command">PREPARE TRANSACTION</code> 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 <code class="command">PREPARE + TRANSACTION</code>. + </p><p> + This command must be used inside a transaction block. Use <a class="link" href="sql-begin.html" title="BEGIN"><code class="command">BEGIN</code></a> to start one. + </p><p> + It is not currently allowed to <code class="command">PREPARE</code> a transaction that + has executed any operations involving temporary tables or the session's + temporary namespace, created any cursors <code class="literal">WITH HOLD</code>, or + executed <code class="command">LISTEN</code>, <code class="command">UNLISTEN</code>, or + <code class="command">NOTIFY</code>. + Those features are too tightly + tied to the current session to be useful in a transaction to be prepared. + </p><p> + If the transaction modified any run-time parameters with <code class="command">SET</code> + (without the <code class="literal">LOCAL</code> option), + those effects persist after <code class="command">PREPARE TRANSACTION</code>, and will not + be affected by any later <code class="command">COMMIT PREPARED</code> or + <code class="command">ROLLBACK PREPARED</code>. Thus, in this one respect + <code class="command">PREPARE TRANSACTION</code> acts more like <code class="command">COMMIT</code> than + <code class="command">ROLLBACK</code>. + </p><p> + All currently available prepared transactions are listed in the + <a class="link" href="view-pg-prepared-xacts.html" title="54.16. pg_prepared_xacts"><code class="structname">pg_prepared_xacts</code></a> + system view. + </p><div class="caution"><h3 class="title">Caution</h3><p> + It is unwise to leave transactions in the prepared state for a long time. + This will interfere with the ability of <code class="command">VACUUM</code> to reclaim + storage, and in extreme cases could cause the database to shut down + to prevent transaction ID wraparound (see <a class="xref" href="routine-vacuuming.html#VACUUM-FOR-WRAPAROUND" title="25.1.5. Preventing Transaction ID Wraparound Failures">Section 25.1.5</a>). 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. + </p><p> + 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 + <a class="xref" href="runtime-config-resource.html#GUC-MAX-PREPARED-TRANSACTIONS">max_prepared_transactions</a> to zero. This will + prevent accidental creation of prepared transactions that might then + be forgotten and eventually cause problems. + </p></div></div><div class="refsect1" id="SQL-PREPARE-TRANSACTION-EXAMPLES"><h2>Examples</h2><p> + Prepare the current transaction for two-phase commit, using + <code class="literal">foobar</code> as the transaction identifier: + +</p><pre class="programlisting"> +PREPARE TRANSACTION 'foobar'; +</pre></div><div class="refsect1" id="id-1.9.3.160.9"><h2>Compatibility</h2><p> + <code class="command">PREPARE TRANSACTION</code> is a + <span class="productname">PostgreSQL</span> 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. + </p></div><div class="refsect1" id="id-1.9.3.160.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-commit-prepared.html" title="COMMIT PREPARED"><span class="refentrytitle">COMMIT PREPARED</span></a>, <a class="xref" href="sql-rollback-prepared.html" title="ROLLBACK PREPARED"><span class="refentrytitle">ROLLBACK PREPARED</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-prepare.html" title="PREPARE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-reassign-owned.html" title="REASSIGN OWNED">Next</a></td></tr><tr><td width="40%" align="left" valign="top">PREPARE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 15.4 Documentation">Home</a></td><td width="40%" align="right" valign="top"> REASSIGN OWNED</td></tr></table></div></body></html>
\ No newline at end of file |