2005-06-18 00:32:51 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/prepare_transaction.sgml
|
2005-06-18 00:32:51 +02:00
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="sql-prepare-transaction">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="sql-prepare-transaction">
|
|
|
|
<primary>PREPARE TRANSACTION</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2005-06-18 00:32:51 +02:00
|
|
|
<refmeta>
|
2010-04-03 09:23:02 +02:00
|
|
|
<refentrytitle>PREPARE TRANSACTION</refentrytitle>
|
2008-11-14 11:22:48 +01:00
|
|
|
<manvolnum>7</manvolnum>
|
2005-06-18 00:32:51 +02:00
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>PREPARE TRANSACTION</refname>
|
|
|
|
<refpurpose>prepare the current transaction for two-phase commit</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2017-10-09 04:00:57 +02:00
|
|
|
PREPARE TRANSACTION <replaceable class="parameter">transaction_id</replaceable>
|
2005-06-18 00:32:51 +02:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>PREPARE TRANSACTION</command> prepares the current transaction
|
2009-04-23 02:23:46 +02:00
|
|
|
for two-phase commit. After this command, the transaction is no longer
|
2005-06-18 00:32:51 +02:00
|
|
|
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>
|
2006-02-26 04:20:46 +01:00
|
|
|
Once prepared, a transaction can later be committed or rolled back
|
2017-11-23 15:39:47 +01:00
|
|
|
with <xref linkend="sql-commit-prepared"/>
|
|
|
|
or <xref linkend="sql-rollback-prepared"/>,
|
2006-02-26 04:20:46 +01:00
|
|
|
respectively. Those commands can be issued from any session, not
|
|
|
|
only the one that executed the original transaction.
|
2005-06-18 00:32:51 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
From the point of view of the issuing session, <command>PREPARE
|
2017-10-09 03:44:17 +02:00
|
|
|
TRANSACTION</command> is not unlike a <command>ROLLBACK</command> command:
|
2005-06-18 00:32:51 +02:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
reason, it becomes a <command>ROLLBACK</command>: the current transaction
|
2005-06-18 00:32:51 +02:00
|
|
|
is canceled.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
2017-10-09 04:00:57 +02:00
|
|
|
<term><replaceable class="parameter">transaction_id</replaceable></term>
|
2005-06-18 00:32:51 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
An arbitrary identifier that later identifies this transaction for
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>COMMIT PREPARED</command> or <command>ROLLBACK PREPARED</command>.
|
2005-06-18 00:32:51 +02:00
|
|
|
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>
|
|
|
|
|
2010-01-25 19:23:10 +01:00
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>PREPARE TRANSACTION</command> is not intended for use in applications
|
2011-01-11 10:45:16 +01:00
|
|
|
or interactive sessions. Its purpose is to allow an external
|
2010-01-25 19:23:10 +01:00
|
|
|
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
|
2017-10-09 03:44:17 +02:00
|
|
|
TRANSACTION</command>.
|
2010-01-25 19:23:10 +01:00
|
|
|
</para>
|
|
|
|
|
2005-06-18 00:32:51 +02:00
|
|
|
<para>
|
2006-02-26 04:20:46 +01:00
|
|
|
This command must be used inside a transaction block. Use <xref
|
2017-11-23 15:39:47 +01:00
|
|
|
linkend="sql-begin"/> to start one.
|
2005-06-18 00:32:51 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
It is not currently allowed to <command>PREPARE</command> a transaction that
|
Restrict the use of temporary namespace in two-phase transactions
Attempting to use a temporary table within a two-phase transaction is
forbidden for ages. However, there have been uncovered grounds for
a couple of other object types and commands which work on temporary
objects with two-phase commit. In short, trying to create, lock or drop
an object on a temporary schema should not be authorized within a
two-phase transaction, as it would cause its state to create
dependencies with other sessions, causing all sorts of side effects with
the existing session or other sessions spawned later on trying to use
the same temporary schema name.
Regression tests are added to cover all the grounds found, the original
report mentioned function creation, but monitoring closer there are many
other patterns with LOCK, DROP or CREATE EXTENSION which are involved.
One of the symptoms resulting in combining both is that the session
which used the temporary schema is not able to shut down completely,
waiting for being able to drop the temporary schema, something that it
cannot complete because of the two-phase transaction involved with
temporary objects. In this case the client is able to disconnect but
the session remains alive on the backend-side, potentially blocking
connection backend slots from being used. Other problems reported could
also involve server crashes.
This is back-patched down to v10, which is where 9b013dc has introduced
MyXactFlags, something that this patch relies on.
Reported-by: Alexey Bashtanov
Author: Michael Paquier
Reviewed-by: Masahiko Sawada
Discussion: https://postgr.es/m/5d910e2e-0db8-ec06-dd5f-baec420513c3@imap.cc
Backpatch-through: 10
2019-01-18 01:21:44 +01:00
|
|
|
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
|
2017-10-27 16:46:06 +02:00
|
|
|
<command>NOTIFY</command>.
|
Fix LISTEN/NOTIFY race condition reported by Laurent Birtz, by postponing
pg_listener modifications commanded by LISTEN and UNLISTEN until the end
of the current transaction. This allows us to hold the ExclusiveLock on
pg_listener until after commit, with no greater risk of deadlock than there
was before. Aside from fixing the race condition, this gets rid of a
truly ugly kludge that was there before, namely having to ignore
HeapTupleBeingUpdated failures during NOTIFY. There is a small potential
incompatibility, which is that if a transaction issues LISTEN or UNLISTEN
and then looks into pg_listener before committing, it won't see any resulting
row insertion or deletion, where before it would have. It seems unlikely
that anyone would be depending on that, though.
This patch also disallows LISTEN and UNLISTEN inside a prepared transaction.
That case had some pretty undesirable properties already, such as possibly
allowing pg_listener entries to be made for PIDs no longer present, so
disallowing it seems like a better idea than trying to maintain the behavior.
2008-03-12 21:11:46 +01:00
|
|
|
Those features are too tightly
|
2005-06-18 00:32:51 +02:00
|
|
|
tied to the current session to be useful in a transaction to be prepared.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
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
|
2009-04-23 02:23:46 +02:00
|
|
|
be affected by any later <command>COMMIT PREPARED</command> or
|
2005-06-18 00:32:51 +02:00
|
|
|
<command>ROLLBACK PREPARED</command>. Thus, in this one respect
|
2017-10-09 03:44:17 +02:00
|
|
|
<command>PREPARE TRANSACTION</command> acts more like <command>COMMIT</command> than
|
|
|
|
<command>ROLLBACK</command>.
|
2005-06-18 00:32:51 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
All currently available prepared transactions are listed in the
|
2006-02-26 04:20:46 +01:00
|
|
|
<link linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>
|
|
|
|
system view.
|
2005-06-18 00:32:51 +02:00
|
|
|
</para>
|
|
|
|
|
2009-04-23 02:23:46 +02:00
|
|
|
<caution>
|
|
|
|
<para>
|
|
|
|
It is unwise to leave transactions in the prepared state for a long time.
|
2017-10-09 03:44:17 +02:00
|
|
|
This will interfere with the ability of <command>VACUUM</command> to reclaim
|
2009-04-23 02:23:46 +02:00
|
|
|
storage, and in extreme cases could cause the database to shut down
|
|
|
|
to prevent transaction ID wraparound (see <xref
|
2017-11-23 15:39:47 +01:00
|
|
|
linkend="vacuum-for-wraparound"/>). Keep in mind also that the transaction
|
2009-04-23 02:23:46 +02:00
|
|
|
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
|
2017-11-23 15:39:47 +01:00
|
|
|
<xref linkend="guc-max-prepared-transactions"/> to zero. This will
|
2009-04-23 02:23:46 +02:00
|
|
|
prevent accidental creation of prepared transactions that might then
|
|
|
|
be forgotten and eventually cause problems.
|
|
|
|
</para>
|
|
|
|
</caution>
|
2005-06-18 00:32:51 +02:00
|
|
|
</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
|
2017-10-09 03:44:17 +02:00
|
|
|
<literal>foobar</literal> as the transaction identifier:
|
2009-04-23 02:23:46 +02:00
|
|
|
|
2005-06-18 00:32:51 +02:00
|
|
|
<programlisting>
|
|
|
|
PREPARE TRANSACTION 'foobar';
|
2011-08-07 09:49:45 +02:00
|
|
|
</programlisting></para>
|
2005-06-18 00:32:51 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2012-04-16 21:40:54 +02:00
|
|
|
<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>
|
|
|
|
|
2005-06-18 00:32:51 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="sql-commit-prepared"/></member>
|
|
|
|
<member><xref linkend="sql-rollback-prepared"/></member>
|
2005-06-18 00:32:51 +02:00
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
</refentry>
|