From 312061cbc76e1a1f3244f89697c4078bc3e8523c Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Thu, 1 Dec 2022 10:45:08 -0500 Subject: [PATCH] revert: add transaction processing chapter with internals info This doc patch (master hash 66bc9d2d3e) was decided to be too significant for backpatching, so reverted in all but master. Also fix SGML file header comment in master. Reported-by: Peter Eisentraut Discussion: https://postgr.es/m/c6304b19-6ff7-f3af-0148-cf7aa7e2fbfd@enterprisedb.com Backpatch-through: 11 --- doc/src/sgml/catalogs.sgml | 7 +- doc/src/sgml/config.sgml | 6 +- doc/src/sgml/datatype.sgml | 3 +- doc/src/sgml/filelist.sgml | 1 - doc/src/sgml/func.sgml | 20 +-- doc/src/sgml/glossary.sgml | 3 +- doc/src/sgml/monitoring.sgml | 6 +- doc/src/sgml/pgrowlocks.sgml | 3 +- doc/src/sgml/postgres.sgml | 1 - doc/src/sgml/ref/release_savepoint.sgml | 62 +++---- doc/src/sgml/ref/rollback.sgml | 8 +- doc/src/sgml/ref/rollback_to.sgml | 5 +- doc/src/sgml/wal.sgml | 6 +- doc/src/sgml/xact.sgml | 205 ------------------------ 14 files changed, 44 insertions(+), 292 deletions(-) delete mode 100644 doc/src/sgml/xact.sgml diff --git a/doc/src/sgml/catalogs.sgml b/doc/src/sgml/catalogs.sgml index 3131f1be82..ebb5a4f3ff 100644 --- a/doc/src/sgml/catalogs.sgml +++ b/doc/src/sgml/catalogs.sgml @@ -10321,8 +10321,7 @@ SCRAM-SHA-256$<iteration count>:&l Virtual ID of the transaction targeted by the lock, - or null if the target is not a virtual transaction ID; see - + or null if the target is not a virtual transaction ID @@ -10331,8 +10330,8 @@ SCRAM-SHA-256$<iteration count>:&l transactionid xid - ID of the transaction targeted by the lock, or null if the target - is not a transaction ID; + ID of the transaction targeted by the lock, + or null if the target is not a transaction ID diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 1a857243a8..be67ff7ced 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -6834,14 +6834,12 @@ local0.* /var/log/postgresql %v - Virtual transaction ID (backendID/localXID); see - + Virtual transaction ID (backendID/localXID) no %x - Transaction ID (0 if none is assigned); see - + Transaction ID (0 if none is assigned) no diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 467b1d727b..2c2a6333ad 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -4811,8 +4811,7 @@ SELECT * FROM pg_attribute xmin and xmax. Transaction identifiers are 32-bit quantities. In some contexts, a 64-bit variant xid8 is used. Unlike xid values, xid8 values increase strictly - monotonically and cannot be reused in the lifetime of a database - cluster. See for more details. + monotonically and cannot be reused in the lifetime of a database cluster. diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml index 759080de9b..19f6699a93 100644 --- a/doc/src/sgml/filelist.sgml +++ b/doc/src/sgml/filelist.sgml @@ -101,7 +101,6 @@ - diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 4bbdcab228..f0155eef7f 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -23223,10 +23223,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); see for details. If executed in a - subtransaction, this will return the top-level transaction ID; - see for details. + performed any database updates). @@ -23243,8 +23240,6 @@ 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 - transaction ID. @@ -23288,9 +23283,6 @@ 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 transaction IDs are included in the snapshot; - subtransaction IDs are not shown; see - for details. @@ -23345,8 +23337,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 (subxid); see for - details. + a subtransaction ID. @@ -23358,9 +23349,8 @@ SELECT collation for ('foo' COLLATE "de_DE"); wraps around every 4 billion transactions. However, the functions shown in use 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; see for details. - The data type pg_snapshot stores information about + of an installation, and can be converted to xid by casting if + required. The data type pg_snapshot stores information about transaction ID visibility at a particular moment in time. Its components are described in . pg_snapshot's textual representation is @@ -23406,7 +23396,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 (subxids). + subtransactions. diff --git a/doc/src/sgml/glossary.sgml b/doc/src/sgml/glossary.sgml index d8073db6dc..9779f341b9 100644 --- a/doc/src/sgml/glossary.sgml +++ b/doc/src/sgml/glossary.sgml @@ -1631,8 +1631,7 @@ 3 (values under that are reserved) and the epoch value is incremented by one. In some contexts, the epoch and xid values are - considered together as a single 64-bit value; see for more details. + considered together as a single 64-bit value. For more information, see diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index 4f10a6b0f3..cb912f60f7 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -869,8 +869,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser backend_xid xid - Top-level transaction identifier of this backend, if any; see - . + Top-level transaction identifier of this backend, if any. @@ -1775,8 +1774,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser virtualxid - Waiting to acquire a virtual transaction ID lock; see - . + Waiting to acquire a virtual transaction ID lock. diff --git a/doc/src/sgml/pgrowlocks.sgml b/doc/src/sgml/pgrowlocks.sgml index 02f31601b0..392d5f1f9a 100644 --- a/doc/src/sgml/pgrowlocks.sgml +++ b/doc/src/sgml/pgrowlocks.sgml @@ -57,8 +57,7 @@ pgrowlocks(text) returns setof record locker xid - Transaction ID of locker, or multixact ID if - multitransaction; see + Transaction ID of locker, or multixact ID if multitransaction multi diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index bdd7a8365f..ffbb150e02 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -267,7 +267,6 @@ break is not needed in a wider output rendering. &brin; &hash; &storage; - &transaction; &bki; &planstats; &backup-manifest; diff --git a/doc/src/sgml/ref/release_savepoint.sgml b/doc/src/sgml/ref/release_savepoint.sgml index e9fc6e5d1c..daf8eb9a43 100644 --- a/doc/src/sgml/ref/release_savepoint.sgml +++ b/doc/src/sgml/ref/release_savepoint.sgml @@ -21,7 +21,7 @@ PostgreSQL documentation RELEASE SAVEPOINT - release a previously defined savepoint + destroy a previously defined savepoint @@ -34,13 +34,23 @@ RELEASE [ SAVEPOINT ] savepoint_name Description - RELEASE SAVEPOINT releases the named savepoint and - all active savepoints that were created after the named savepoint, - and frees their resources. All changes made since the creation of - the savepoint that didn't already get rolled back are merged into - the transaction or savepoint that was active when the named savepoint - was created. Changes made after RELEASE SAVEPOINT - will also be part of this active transaction or savepoint. + RELEASE SAVEPOINT destroys a savepoint previously defined + in the current transaction. + + + + Destroying a savepoint makes it unavailable as a rollback point, + but it has no other user visible behavior. It does not undo the + effects of commands executed after the savepoint was established. + (To do that, see .) + Destroying a savepoint when + it is no longer needed allows the system to reclaim some resources + earlier than transaction end. + + + + RELEASE SAVEPOINT also destroys all savepoints that were + established after the named savepoint was established. @@ -52,7 +62,7 @@ RELEASE [ SAVEPOINT ] savepoint_name savepoint_name - The name of the savepoint to release. + The name of the savepoint to destroy. @@ -68,7 +78,7 @@ RELEASE [ SAVEPOINT ] savepoint_name It is not possible to release a savepoint when the transaction is in - an aborted state; to do that, use . + an aborted state. @@ -83,7 +93,7 @@ RELEASE [ SAVEPOINT ] savepoint_name Examples - To establish and later release a savepoint: + To establish and later destroy a savepoint: BEGIN; INSERT INTO table1 VALUES (3); @@ -94,36 +104,6 @@ COMMIT; The above transaction will insert both 3 and 4. - - - A more complex example with multiple nested subtransactions: - -BEGIN; - INSERT INTO table1 VALUES (1); - SAVEPOINT sp1; - INSERT INTO table1 VALUES (2); - SAVEPOINT sp2; - INSERT INTO table1 VALUES (3); - RELEASE SAVEPOINT sp2; - INSERT INTO table1 VALUES (4))); -- generates an error - - In this example, the application requests the release of the savepoint - sp2, which inserted 3. This changes the insert's - transaction context to sp1. When the statement - attempting to insert value 4 generates an error, the insertion of 2 and - 4 are lost because they are in the same, now-rolled back savepoint, - and value 3 is in the same transaction context. The application can - now only choose one of these two commands, since all other commands - will be ignored: - - ROLLBACK; - ROLLBACK TO SAVEPOINT sp1; - - Choosing ROLLBACK will abort everything, including - value 1, whereas ROLLBACK TO SAVEPOINT sp1 will retain - value 1 and allow the transaction to continue. - - diff --git a/doc/src/sgml/ref/rollback.sgml b/doc/src/sgml/ref/rollback.sgml index 7f8a088c7f..1357eaa832 100644 --- a/doc/src/sgml/ref/rollback.sgml +++ b/doc/src/sgml/ref/rollback.sgml @@ -56,10 +56,10 @@ ROLLBACK [ WORK | TRANSACTION ] [ AND [ NO ] CHAIN ] AND CHAIN - If AND CHAIN is specified, a new (not aborted) - transaction is immediately started with the same transaction - characteristics (see ) as the - just finished one. Otherwise, no new transaction is started. + If AND CHAIN is specified, a new transaction is + immediately started with the same transaction characteristics (see ) as the just finished one. Otherwise, + no new transaction is started. diff --git a/doc/src/sgml/ref/rollback_to.sgml b/doc/src/sgml/ref/rollback_to.sgml index 827235eec2..4d5647a302 100644 --- a/doc/src/sgml/ref/rollback_to.sgml +++ b/doc/src/sgml/ref/rollback_to.sgml @@ -35,9 +35,8 @@ ROLLBACK [ WORK | TRANSACTION ] TO [ SAVEPOINT ] savepoint_name Roll back all commands that were executed after the savepoint was - established and then start a new subtransaction at the same transaction level. - The savepoint remains valid and can be rolled back to again later, - if needed. + established. The savepoint remains valid and can be rolled back to + again later, if needed. diff --git a/doc/src/sgml/wal.sgml b/doc/src/sgml/wal.sgml index 8f8ff2dfb9..7a2e111bfc 100644 --- a/doc/src/sgml/wal.sgml +++ b/doc/src/sgml/wal.sgml @@ -4,9 +4,8 @@ Reliability and the Write-Ahead Log - This chapter explains how to control the reliability of - PostgreSQL, including details about the - Write-Ahead Log. + This chapter explains how the Write-Ahead Log is used to obtain + efficient, reliable operation. @@ -813,5 +812,4 @@ seem to be a problem in practice. - diff --git a/doc/src/sgml/xact.sgml b/doc/src/sgml/xact.sgml deleted file mode 100644 index c0f4993a0d..0000000000 --- a/doc/src/sgml/xact.sgml +++ /dev/null @@ -1,205 +0,0 @@ - - - - - Transaction Processing - - - 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 - - - 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 TransactionIds (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 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 - return xid8 values. Xids are used as the - basis for PostgreSQL's 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 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. - - - - - - Transactions and Locking - - - The transaction IDs of currently executing transactions are shown in - 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 - extension. Row-level read locks might also require the assignment - of multixact IDs (mxid; see ). - - - - - - Subtransactions - - - 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 - - - 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. - - - -