<!-- doc/src/sgml/xact.sgml -->

<chapter id="transactions">

 <title>Transaction Processing</title>

 <para>
  This chapter provides an overview of the internals of
  <productname>PostgreSQL</productname>'s transaction management system.
  The word transaction is often abbreviated as <firstterm>xact</firstterm>.
 </para>

 <sect1 id="transaction-id">

  <title>Transactions and Identifiers</title>

  <para>
   Transactions can be created explicitly using <command>BEGIN</command>
   or <command>START TRANSACTION</command> and ended using
   <command>COMMIT</command> or <command>ROLLBACK</command>.  SQL
   statements outside of explicit transactions automatically use
   single-statement transactions.
  </para>

  <para>
   Every transaction is identified by a unique
   <literal>VirtualTransactionId</literal> (also called
   <literal>virtualXID</literal> or <literal>vxid</literal>), which
   is comprised of a backend's process number (or <literal>procNumber</literal>)
   and a sequentially-assigned number local to each backend, known as
   <literal>localXID</literal>.  For example, the virtual transaction
   ID <literal>4/12532</literal> has a <literal>procNumber</literal>
   of <literal>4</literal> and a <literal>localXID</literal> of
   <literal>12532</literal>.
  </para>

  <para>
   Non-virtual <literal>TransactionId</literal>s (or <type>xid</type>),
   e.g., <literal>278394</literal>, are assigned sequentially to
   transactions from a global counter used by all databases within
   the <productname>PostgreSQL</productname> cluster.  This assignment
   happens when a transaction first writes to the database. This means
   lower-numbered xids started writing before higher-numbered xids.
   Note that the order in which transactions perform their first database
   write might be different from the order in which the transactions
   started, particularly if the transaction started with statements that
   only performed database reads.
  </para>

  <para>
   The internal transaction ID type <type>xid</type> is 32 bits wide
   and <link linkend="vacuum-for-wraparound">wraps around</link> every
   4 billion transactions. A 32-bit epoch is incremented during each
   wraparound. There is also a 64-bit type <type>xid8</type> which
   includes this epoch and therefore does not wrap around during the
   life of an installation;  it can be converted to xid by casting.
   The functions in <xref linkend="functions-pg-snapshot"/>
   return <type>xid8</type> values.  Xids are used as the
   basis for <productname>PostgreSQL</productname>'s <link
   linkend="mvcc">MVCC</link> concurrency mechanism and streaming
   replication.
  </para>

  <para>
   When a top-level transaction with a (non-virtual) xid commits,
   it is marked as committed in the <filename>pg_xact</filename>
   directory. Additional information is recorded in the
   <filename>pg_commit_ts</filename> directory if <xref
   linkend="guc-track-commit-timestamp"/> is enabled.
  </para>

  <para>
   In addition to <literal>vxid</literal> and <literal>xid</literal>,
   prepared transactions are also assigned Global Transaction
   Identifiers (<acronym>GID</acronym>). GIDs are string literals up
   to 200 bytes long, which must be unique amongst other currently
   prepared transactions.  The mapping of GID to xid is shown in <link
   linkend="view-pg-prepared-xacts"><structname>pg_prepared_xacts</structname></link>.
  </para>
 </sect1>

 <sect1 id="xact-locking">

  <title>Transactions and Locking</title>

  <para>
   The transaction IDs of currently executing transactions are shown in
   <link linkend="view-pg-locks"><structname>pg_locks</structname></link>
   in columns <structfield>virtualxid</structfield> and
   <structfield>transactionid</structfield>.  Read-only transactions
   will have <structfield>virtualxid</structfield>s but NULL
   <structfield>transactionid</structfield>s, while both columns will be
   set in read-write transactions.
  </para>

  <para>
   Some lock types