head	1.11;
access;
symbols
	REL9_0_0:1.11
	REL9_1_ALPHA1:1.11
	REL9_0_RC1:1.11
	REL9_0_BETA4:1.11
	REL9_0_STABLE:1.11.0.2
	REL9_0_BETA3:1.11
	REL9_0_BETA2:1.11
	REL8_1_21:1.3.2.1
	REL8_2_17:1.5.2.1
	REL8_3_11:1.6.2.1
	REL8_4_4:1.9
	REL9_0_BETA1:1.11
	REL9_0_ALPHA5_BRANCH:1.10.0.4
	REL9_0_ALPHA5:1.10
	REL8_1_20:1.3.2.1
	REL8_2_16:1.5.2.1
	REL8_3_10:1.6.2.1
	REL8_4_3:1.9
	REL9_0_ALPHA4:1.10
	REL9_0_ALPHA4_BRANCH:1.10.0.2
	REL8_5_ALPHA3:1.9
	REL8_5_ALPHA3_BRANCH:1.9.0.8
	REL8_1_19:1.3.2.1
	REL8_2_15:1.5.2.1
	REL8_3_9:1.6.2.1
	REL8_4_2:1.9
	REL8_5_ALPHA2:1.9
	REL8_5_ALPHA2_BRANCH:1.9.0.6
	REL8_1_18:1.3.2.1
	REL8_2_14:1.5.2.1
	REL8_3_8:1.6.2.1
	REL8_4_1:1.9
	REL8_5_ALPHA1:1.9
	REL8_5_ALPHA1_BRANCH:1.9.0.4
	REL8_4_STABLE:1.9.0.2
	REL8_4_0:1.9
	REL8_4_RC2:1.9
	REL8_4_RC1:1.9
	REL8_4_BETA2:1.9
	REL8_4_BETA1:1.8
	REL8_1_17:1.3.2.1
	REL8_2_13:1.5.2.1
	REL8_3_7:1.6.2.1
	REL8_1_16:1.3.2.1
	REL8_2_12:1.5.2.1
	REL8_3_6:1.6.2.1
	REL8_1_15:1.3.2.1
	REL8_2_11:1.5.2.1
	REL8_3_5:1.6.2.1
	REL8_1_14:1.3.2.1
	REL8_2_10:1.5.2.1
	REL8_3_4:1.6.2.1
	REL8_1_13:1.3.2.1
	REL8_2_9:1.5.2.1
	REL8_3_3:1.6.2.1
	REL8_1_12:1.3.2.1
	REL8_2_8:1.5.2.1
	REL8_3_2:1.6.2.1
	REL8_2_7:1.5.2.1
	REL8_3_1:1.6.2.1
	REL8_3_STABLE:1.6.0.2
	REL8_3_0:1.6
	REL8_3_RC2:1.6
	REL8_1_11:1.3
	REL8_2_6:1.5
	REL8_3_RC1:1.6
	REL8_3_BETA4:1.6
	REL8_3_BETA3:1.6
	REL8_3_BETA2:1.6
	REL8_3_BETA1:1.6
	REL8_1_10:1.3
	REL8_2_5:1.5
	REL8_1_9:1.3
	REL8_2_4:1.5
	REL8_1_8:1.3
	REL8_2_3:1.5
	REL8_1_7:1.3
	REL8_2_2:1.5
	REL8_1_6:1.3
	REL8_2_1:1.5
	REL8_2_STABLE:1.5.0.2
	REL8_2_0:1.5
	REL8_2_RC1:1.5
	REL8_2_BETA3:1.5
	REL8_2_BETA2:1.5
	REL8_1_5:1.3
	REL8_2_BETA1:1.5
	REL8_1_4:1.3
	REL8_1_3:1.3
	REL8_1_2:1.3
	REL8_1_1:1.3
	REL8_1_STABLE:1.3.0.2
	REL8_1_0:1.3
	REL8_1_0RC1:1.3
	REL8_1_0BETA4:1.3
	REL8_1_0BETA3:1.3
	REL8_1_0BETA2:1.3
	REL8_1_0BETA1:1.2;
locks; strict;
comment	@# @;


1.11
date	2010.04.03.07.23.02;	author petere;	state Exp;
branches;
next	1.10;

1.10
date	2010.01.25.18.23.10;	author heikki;	state Exp;
branches;
next	1.9;

1.9
date	2009.04.23.00.23.45;	author tgl;	state Exp;
branches;
next	1.8;

1.8
date	2008.11.14.10.22.47;	author petere;	state Exp;
branches;
next	1.7;

1.7
date	2008.03.12.20.11.45;	author tgl;	state Exp;
branches;
next	1.6;

1.6
date	2007.09.11.00.06.41;	author tgl;	state Exp;
branches
	1.6.2.1;
next	1.5;

1.5
date	2006.09.16.00.30.19;	author momjian;	state Exp;
branches
	1.5.2.1;
next	1.4;

1.4
date	2006.02.26.03.20.46;	author neilc;	state Exp;
branches;
next	1.3;

1.3
date	2005.08.30.01.37.38;	author tgl;	state Exp;
branches
	1.3.2.1;
next	1.2;

1.2
date	2005.08.01.19.38.03;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	2005.06.17.22.32.42;	author tgl;	state Exp;
branches;
next	;

1.3.2.1
date	2008.03.12.20.12.14;	author tgl;	state Exp;
branches;
next	;

1.5.2.1
date	2008.03.12.20.12.01;	author tgl;	state Exp;
branches;
next	;

1.6.2.1
date	2008.03.12.20.11.54;	author tgl;	state Exp;
branches;
next	;


desc
@@


1.11
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.10 2010/01/25 18:23:10 heikki Exp $
PostgreSQL documentation
-->

<refentry id="SQL-PREPARE-TRANSACTION">
 <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>

 <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 <xref linkend="sql-commit-prepared">
   or <xref linkend="sql-rollback-prepared">,
   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>
   <command>PREPARE TRANSACTION</> is not intended for use in applications
   or interactive sessions. It's 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</>.
  </para>

  <para>
   This command must be used inside a transaction block. Use <xref
   linkend="sql-begin"> to start one.
  </para>

  <para>
   It is not currently allowed to <command>PREPARE</> a transaction that
   has executed any operations involving temporary tables,
   created any cursors <literal>WITH HOLD</>, or executed
   <command>LISTEN</> or <command>UNLISTEN</>.
   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</>
   (without the <literal>LOCAL</> option),
   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
   <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</> 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 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"></member>
   <member><xref linkend="sql-rollback-prepared"></member>
  </simplelist>
 </refsect1>

</refentry>
@


1.10
log
@Add note that PREPARE TRANSACTION is for transaction managers, not
regular applications. Also add a comment pointing out that tab-complition
for PREPARE TRANSACTION is missing on purpose.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.9 2009/04/23 00:23:45 tgl Exp $
d8 1
a8 1
  <refentrytitle id="sql-prepare-transaction-title">PREPARE TRANSACTION</refentrytitle>
d42 2
a43 2
   with <xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title">
   or <xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title">,
d96 1
a96 1
   linkend="sql-begin" endterm="sql-begin-title"> to start one.
d164 2
a165 2
   <member><xref linkend="sql-commit-prepared" endterm="sql-commit-prepared-title"></member>
   <member><xref linkend="sql-rollback-prepared" endterm="sql-rollback-prepared-title"></member>
@


1.9
log
@Change the default value of max_prepared_transactions to zero, and add
documentation warnings against setting it nonzero unless active use of
prepared transactions is intended and a suitable transaction manager has been
installed.  This should help to prevent the type of scenario we've seen
several times now where a prepared transaction is forgotten and eventually
causes severe maintenance problems (or even anti-wraparound shutdown).

The only real reason we had the default be nonzero in the first place was to
support regression testing of the feature.  To still be able to do that,
tweak pg_regress to force a nonzero value during "make check".  Since we
cannot force a nonzero value in "make installcheck", add a variant regression
test "expected" file that shows the results that will be obtained when
max_prepared_transactions is zero.

Also, extend the HINT messages for transaction wraparound warnings to mention
the possibility that old prepared transactions are causing the problem.

All per today's discussion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.8 2008/11/14 10:22:47 petere Exp $
d86 9
@


1.8
log
@Set SQL man pages to be section 7 by default, and only transform them to
another section if required by the platform (instead of the old way of
building them in section "l" and always transforming them to the
platform-specific section).

This speeds up the installation on common platforms, and it avoids some
funny business with the man page tools and build process.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.7 2008/03/12 20:11:45 tgl Exp $
d33 1
a33 1
   for two-phase commit. After this command, the transaction is no longer 
d103 1
a103 1
   be affected by any later <command>COMMIT PREPARED</command> or 
d115 22
a136 20
  <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>

  <para>
   If you make any serious use of prepared transactions, you will probably
   want to increase the value of <xref
   linkend="guc-max-prepared-transactions">, as the default setting is
   quite small (to avoid wasting resources for those who don't use it).
   It is recommendable to make it at least equal to
   <xref linkend="guc-max-connections">, so that every session can have
   a prepared transaction pending.
  </para>
d144 1
a144 1
   
@


1.7
log
@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.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.6 2007/09/11 00:06:41 tgl Exp $
d9 1
@


1.6
log
@Arrange for SET LOCAL's effects to persist until the end of the current top
transaction, unless rolled back or overridden by a SET clause for the same
variable attached to a surrounding function call.  Per discussion, these
seem the best semantics.  Note that this is an INCOMPATIBLE CHANGE: in 8.0
through 8.2, SET LOCAL's effects disappeared at subtransaction commit
(leading to behavior that made little sense at the SQL level).

I took advantage of the opportunity to rewrite and simplify the GUC variable
save/restore logic a little bit.  The old idea of a "tentative" value is gone;
it was a hangover from before we had a stack.  Also, we no longer need a stack
entry for every nesting level, but only for those in which a variable's value
actually changed.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.5 2006/09/16 00:30:19 momjian Exp $
d91 4
a94 2
   has executed any operations involving temporary tables or
   created any cursors <literal>WITH HOLD</>.  Those features are too tightly
@


1.6.2.1
log
@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.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.6 2007/09/11 00:06:41 tgl Exp $
d91 2
a92 4
   has executed any operations involving temporary tables,
   created any cursors <literal>WITH HOLD</>, or executed
   <command>LISTEN</> or <command>UNLISTEN</>.
   Those features are too tightly
@


1.5
log
@Remove emacs info from footer of SGML files.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.4 2006/02/26 03:20:46 neilc Exp $
d97 2
a98 1
   If the transaction modified any run-time parameters with <command>SET</>,
@


1.5.2.1
log
@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.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.5 2006/09/16 00:30:19 momjian Exp $
d91 2
a92 4
   has executed any operations involving temporary tables,
   created any cursors <literal>WITH HOLD</>, or executed
   <command>LISTEN</> or <command>UNLISTEN</>.
   Those features are too tightly
@


1.4
log
@Minor SGML work: add some more hyperlinks, where appropriate.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.3 2005/08/30 01:37:38 tgl Exp $
a154 17

<!-- 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:
-->
@


1.3
log
@Mention max_prepared_transactions in PREPARE TRANSACTION reference page,
per Bruce's suggestion.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.2 2005/08/01 19:38:03 momjian Exp $
d40 5
a44 5
   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.
d85 2
a86 2
   This command must be used inside a transaction block. Use
   <command>BEGIN</command> to start one.
d107 2
a108 1
   <structname>pg_prepared_xacts</> system view.
@


1.3.2.1
log
@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.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.3 2005/08/30 01:37:38 tgl Exp $
d91 2
a92 4
   has executed any operations involving temporary tables,
   created any cursors <literal>WITH HOLD</>, or executed
   <command>LISTEN</> or <command>UNLISTEN</>.
   Those features are too tightly
@


1.2
log
@nor -> or.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql/doc/src/sgml/ref/prepare_transaction.sgml,v 1.1 2005/06/17 22:32:42 tgl Exp $
d120 10
@


1.1
log
@Two-phase commit.  Original patch by Heikki Linnakangas, with additional
hacking by Alvaro Herrera and Tom Lane.
@
text
@d2 1
a2 1
$PostgreSQL$
d91 1
a91 1
   has executed any operations involving temporary tables nor
@

