Transaction Processing {#transactions}
======================

This chapter provides an overview of the internals of PostgreSQL\'s
transaction management system. The word transaction is often abbreviated
as xact.

Transactions and Identifiers {#transaction-id}
============================

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

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

Non-virtual `TransactionId`s (or `xid`), e.g., `278394`, are assigned
sequentially to transactions from a global counter used by all databases
within the PostgreSQL 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.

The internal transaction ID type `xid` is 32 bits wide and [wraps
around](#vacuum-for-wraparound) every 4 billion transactions. A 32-bit
epoch is incremented during each wraparound. There is also a 64-bit type
`xid8` 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 [???](#functions-pg-snapshot) return `xid8`
values. Xids are used as the basis for PostgreSQL\'s [MVCC](#mvcc)
concurrency mechanism and streaming replication.

When a top-level transaction with a (non-virtual) xid commits, it is
marked as committed in the `pg_xact` directory. Additional information
is recorded in the `pg_commit_ts` directory if
[???](#guc-track-commit-timestamp) is enabled.

In addition to `vxid` and `xid`, prepared transactions are also assigned
Global Transaction Identifiers (GID). 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
[pg\_prepared\_xacts](#view-pg-prepared-xacts).

Transactions and Locking {#xact-locking}
========================

The transaction IDs of currently executing transactions are shown in
[pg\_locks](#view-pg-locks) in columns virtualxid and transactionid.
Read-only transactions will have virtualxids but NULL transactionids,
while both columns will be set in read-write transactions.

Some lock types wait on virtualxid, while other types wait on
transactionid. Row-level read and write locks are recorded directly in
the locked rows and can be inspected using the [???](#pgrowlocks)
extension. Row-level read locks might also require the assignment of
multixact IDs (`mxid`; see [???](#vacuum-for-multixact-wraparound)).

Subtransactions {#subxacts}
===============

Subtransactions are started inside transactions, allowing large
transactions to be broken into smaller units. Subtransactions can commit
or abort without affecting their parent transactions, allowing parent
transactions to continue. This allows errors to be handled more easily,
which is a common application development pattern. The word
subtransaction is often abbreviated as subxact.

Subtransactions can be started explicitly using the `SAVEPOINT` command,
but can also be started in other ways, such as PL/pgSQL\'s `EXCEPTION`
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.

If a subtransaction is assigned a non-virtual transaction ID, its
transaction ID is referred to as a "subxid". 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.

The immediate parent xid of each subxid is recorded in the `pg_subtrans`
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.

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.

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

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 `pg_subtrans`.

Two-Phase Transactions {#two-phase}
======================

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

When the user executes `PREPARE TRANSACTION`, the only possible next
commands are `COMMIT PREPARED` or `ROLLBACK PREPARED`. 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 `pg_twophase` directory. Transactions that are currently prepared
can be inspected using [pg\_prepared\_xacts](#view-pg-prepared-xacts).
