diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index de450cd661..12263f5fd5 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -103,6 +103,7 @@ + diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index ee515cec8f..6aca1e756a 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -24635,6 +24635,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); Returns the current transaction's ID. It will assign a new one if the current transaction does not have one already (because it has not performed any database updates). + If executed in a subtransaction this will return the top-level xid. @@ -24651,6 +24652,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); ID is assigned yet. (It's best to use this variant if the transaction might otherwise be read-only, to avoid unnecessary consumption of an XID.) + If executed in a subtransaction this will return the top-level xid. @@ -24694,6 +24696,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); Returns a current snapshot, a data structure showing which transaction IDs are now in-progress. + Only top-level xids are included in the snapshot; subxids are not shown. @@ -24748,7 +24751,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); Is the given transaction ID visible according to this snapshot (that is, was it completed before the snapshot was taken)? Note that this function will not give the correct answer for - a subtransaction ID. + a subtransaction ID (subxid). @@ -24807,7 +24810,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); xmax and not in this list was already completed at the time of the snapshot, and thus is either visible or dead according to its commit status. This list does not include the transaction IDs of - subtransactions. + subtransactions (subxids). diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml index 5f244cdd3c..53d830998c 100644 --- a/doc/src/sgml/ref/commit.sgml +++ b/doc/src/sgml/ref/commit.sgml @@ -62,6 +62,9 @@ COMMIT [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] linkend="sql-set-transaction"/>) as the just finished one. Otherwise, no new transaction is started. + + The SQL Standard describes this as a chained transaction. + diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index 142f71e774..02b118fc04 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -56,11 +56,14 @@ ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] AND CHAIN - If AND CHAIN is specified, a new transaction is + If AND CHAIN is specified, a new unaborted transaction is immediately started with the same transaction characteristics (see ) as the just finished one. Otherwise, no new transaction is started. + + The SQL Standard describes this as a chained transaction. + diff --git a/doc/src/sgml/xact.sgml b/doc/src/sgml/xact.sgml new file mode 100644 index 0000000000..9c34b6e721 --- /dev/null +++ b/doc/src/sgml/xact.sgml @@ -0,0 +1,225 @@ + + + + +Transaction Management + + +This chapter provides an overview of transaction management for +PostgreSQL databases. +The word transaction is often abbreviated to "xact". + + + +PostgreSQL supports transactions and chained +transactions according to the SQL Standard. +PostgreSQL supports SAVEPOINTs through the +implementation-defined mechanism of subtransactions, which offer a superset of +the required features. Prepared transactions allow PostgreSQL to implement what +the SQL Standard refers to as encompassing transactions belonging to an external +agent. + + + +Some features implemented in other databases, such as +autonomous transactions and nested transactions are not supported +by PostgreSQL, though be careful since those terms may +be used slightly differently in various external contexts. + + + + +Transactions and Identifiers + + +Transactions may be managed explicitly using BEGIN and +COMMIT, known as a transaction block. +A transaction will also be started and ended implicitly for +each request when outside of a transaction block. + + + +All transactions are identified by a unique VirtualTransactionId (virtualxid or +vxid), e.g. 4/12532, which is comprised of the BackendId (in this example, 4) +and a sequentially-assigned number unique to that backend, known as LocalXid +(in this example, 12532). + + + +If a transaction attempts to write to the database, it will first be assigned a +TransactionId (xid), e.g. 278394. xids are assigned sequentially using a global +counter used by all databases within a postgresql cluster (instance). This +property is used by the transaction system to say that if one xid is earlier +than another xid, then the earlier transaction attempted to write before the +later xid. However, the start and end of those two transactions are not +constrained to occur in that sequence. + + + +When a top-level transaction with an assigned xid commits, it is marked as +committed in the pg_xact directory. Additional information may also be recorded +in the pg_commit_ts directory. + + + +The internal transaction ID type xid is 32-bits wide and wraps around every +4 billion transactions. A 32-bit epoch is incremented by one for each turn +of the transaction clock. There is also a 64-bit type xid8 that does not wrap +around during the life of an installation, and can be converted to xid by +casting if required. + + + +Functions to inspect xids are shown in in Table 9.81, which return values of +type xid8. + + + +xids are used as the basis for PostgreSQL's MVCC +visibility mechanism, described elsewhere. +Hot Standby, or Read Replica servers, emulate the transaction management +details described here so that users have MVCC visibility with read-only +transactions. + + + +In addition to vxid and xid, when a transaction is prepared it is also identified by a +Global Transaction Identifier (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 only shown in pg_prepared_xacts. + + + + + + +Transactions and Locking + + +Currently-executing transactions are shown in +pg_locks. +in columns "virtualxid" (text) and "transactionid" (xid). +Read-only transactions will have a virtualxid but a NULL xid, while read-write +transactions will have both a virtualxid and an xid assigned. + + + +Virtualxid is a text column, rather than a separate datatype. + + + +Lock waits on table-level locks are shown against virtualxid, while lock waits +against row-level locks are shown against transactionid. + + + +Row-level locks are recorded directly onto the locked rows. Row-level locks can +be inspected using the pgrowlocks extension. + + + +Row-level read locks may require the assignment of a multixact ID (mxid). Mxids +are recorded in the pg_multixact directory. + + + + + + +Subtransactions + + +Subtransactions may be started from the main transaction, allowing a large +transaction to be broken into smaller units. +Subtransactions may commit or abort without affecting their parent +transaction, allowing the parent transaction to continue. This allows ERRORs +to be handled more easily, so is a common application development pattern. +Committed subtransactions are only recorded as committed if the main +transaction commits, otherwise any work done in a subtransaction will be +rolled back. The word subtransaction is often abbreviated as "subxact". + + + +Subtransactions may be started explicitly by using SAVEPOINT, +but may also be started in other ways, such as PL/pgSQL's +EXCEPTION clause. +PL/Python and PL/TCL also support explicit subtransactions. +Working with the C API, users may also call BeginInternalSubTransaction(). + + + +Over time, a transaction may have many child subtransactions. +Subtransactions can also be started from other subtransactions. +As a result, the arrangement of the main transaction and +its child subtransactions form a hierarchy or tree, which is why we refer +to the main transaction as the top-level transaction. +Thus, each subtransaction has only one parent transaction. + + + +At present in PostgreSQL, only one transaction or +subtransaction can be active at one time. When a subtransaction ends, the parent +transaction becomes active again. + + + +If a subtransaction is assigned an xid, we refer to this as a subxid. Read-only +subtransactions are not assigned a subxid, but when a subtransaction attempts to +write, it will be assigned a subxid. We ensure that all of a subxid's parents, up +to and including the top-level transaction are also assigned an xid. +We ensure that a parent xid is always earlier than any of its child subxids. + + + +The 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 the committed child subtransactions with +assigned subxids will be recorded as committed. When a top-level transaction with +an assigned xid commits, all of its committed child subtransactions are also +marked as committed in the pg_xact directory. + + + +The more subtransactions each transaction uses, the greater the overhead for +transaction management. Up to 64 subxids are cached in shared memory for each backend; +after that point, the overhead increases more significantly since we must look up +the entry in pg_subtrans for each xid. + + + + + + +Two-Phase Transactions + + +PostgreSQL supports a two-phase commit (2PC) protocol +that allows multiple distributed systems to work together in a transactional manner. +The commands PREPARE TRANSACTION, COMMIT PREPARED +and ROLLBACK PREPARED are extensions to the SQL Standard, since the +SQL syntax is not yet part of the standard, though the Standard does refer to encompassing +transactions made by an external SQL agent. Two-phase transactions are intended +for use programmatically 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, this prevents further +work from being performed other than a COMMIT PREPARED or +ROLLBACK PREPARED. In general, this prepared state is intended +to be of very short duration, but external availability issues may mean transactions stay +in this state for an extended interval. Transactions that were prepared before the +last checkpoint are stored in files in the pg_twophase directory. In the typical +case, shorter-lived prepared transactions are stored only in shared memory and WAL. +Transactions that are currently prepared can be inspected using +pg_prepared_xacts. + + + + +