a common application development pattern.
   The word subtransaction is often abbreviated as
   <firstterm>subxact</firstterm>.
  </para>

  <para>
   Subtransactions can be started explicitly using the
   <command>SAVEPOINT</command> command, but can also be started in
   other ways, such as PL/pgSQL's <literal>EXCEPTION</literal> clause.
   PL/Python and PL/Tcl also support explicit subtransactions.
   Subtransactions can also be started from other subtransactions.
   The top-level transaction and its child subtransactions form a
   hierarchy or tree, which is why we refer to the main transaction as
   the top-level transaction.
  </para>

  <para>
   If a subtransaction is assigned a non-virtual transaction ID,
   its transaction ID is referred to as a <quote>subxid</quote>.
   Read-only subtransactions are not assigned subxids, but once they
   attempt to write, they will be assigned one. This also causes all of
   a subxid's parents, up to and including the top-level transaction,
   to be assigned non-virtual transaction ids.  We ensure that a parent
   xid is always lower than any of its child subxids.
  </para>

  <para>
   The immediate parent xid of each subxid is recorded in the
   <filename>pg_subtrans</filename> directory. No entry is made for
   top-level xids since they do not have a parent, nor is an entry made
   for read-only subtransactions.
  </para>

  <para>
   When a subtransaction commits, all of its committed child
   subtransactions with subxids will also be considered subcommitted
   in that transaction.  When a subtransaction aborts, all of its child
   subtransactions will also be considered aborted.
  </para>

  <para>
   When a top-level transaction with an xid commits, all of its
   subcommitted child subtransactions are also persistently recorded
   as committed in the <filename>pg_xact</filename> subdirectory.  If the
   top-level transaction aborts, all its subtransactions are also aborted,
   even if they were subcommitted.
  </para>

  <para>
   The more subtransactions each transaction keeps open (not
   rolled back or released), the greater the transaction management
   overhead. Up to 64 open subxids are cached in shared memory for
   each backend; after that point, the storage I/O overhead increases
   significantly due to additional lookups of subxid entries in
   <filename>pg_subtrans</filename>.
  </para>
 </sect1>

 <sect1 id="two-phase">

  <title>Two-Phase Transactions</title>

  <para>
   <productname>PostgreSQL</productname> supports a two-phase commit (2PC)
   protocol that allows multiple distributed systems to work together
   in a transactional manner.  The commands are <command>PREPARE
   TRANSACTION</command>, <command>COMMIT PREPARED</command> and
   <command>ROLLBACK PREPARED</command>.  Two-phase transactions
   are intended for use by external transaction management systems.
   <productname>PostgreSQL</productname> follows the features and model
   proposed by the X/Open XA standard, but does not implement some less
   often used aspects.
  </para>

  <para>
   When the user executes <command>PREPARE TRANSACTION</command>, the
   only possible next commands are <command>COMMIT PREPARED</command>
   or <command>ROLLBACK PREPARED</command>. In general, this prepared
   state is intended to be of very short duration, but external
   availability issues might mean transactions stay in this state
   for an extended interval. Short-lived prepared
   transactions are stored only in shared memory and WAL.
   Transactions that span checkpoints are recorded in the
   <filename>pg_twophase</filename> directory.  Transactions
   that are currently prepared can be inspected using <link
   linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>.
  </para>
 </sect1>

</chapter>