summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/sql-prepare-transaction.html
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:15:05 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-04 12:15:05 +0000
commit46651ce6fe013220ed397add242004d764fc0153 (patch)
tree6e5299f990f88e60174a1d3ae6e48eedd2688b2b /doc/src/sgml/html/sql-prepare-transaction.html
parentInitial commit. (diff)
downloadpostgresql-14-46651ce6fe013220ed397add242004d764fc0153.tar.xz
postgresql-14-46651ce6fe013220ed397add242004d764fc0153.zip
Adding upstream version 14.5.upstream/14.5upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/src/sgml/html/sql-prepare-transaction.html')
-rw-r--r--doc/src/sgml/html/sql-prepare-transaction.html90
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..04a9125
--- /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 xmlns="http://www.w3.org/TR/xhtml1/transitional" 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 14.5 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></hr></div><div class="refentry" id="SQL-PREPARE-TRANSACTION"><div class="titlepage"></div><a id="id-1.9.3.159.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.159.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.159.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.159.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="52.78. 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.159.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.159.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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navfooter"><hr></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 14.5 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
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-15 07:48:47 +0000