From 4c04be9b05ad2ec5acd27c3417bf075c13cab134 Mon Sep 17 00:00:00 2001 From: Thomas Munro Date: Tue, 7 Apr 2020 11:33:56 +1200 Subject: Introduce xid8-based functions to replace txid_XXX. The txid_XXX family of fmgr functions exposes 64 bit transaction IDs to users as int8. Now that we have an SQL type xid8 for FullTransactionId, define a new set of functions including pg_current_xact_id() and pg_current_snapshot() based on that. Keep the old functions around too, for now. It's a bit sneaky to use the same C functions for both, but since the binary representation is identical except for the signedness of the type, and since older functions are the ones using the wrong signedness, and since we'll presumably drop the older ones after a reasonable period of time, it seems reasonable to switch to FullTransactionId internally and share the code for both. Reviewed-by: Fujii Masao Reviewed-by: Takao Fujii Reviewed-by: Yoshikazu Imai Reviewed-by: Mark Dilger Discussion: https://postgr.es/m/20190725000636.666m5mad25wfbrri%40alap3.anarazel.de --- doc/src/sgml/datatype.sgml | 8 +- doc/src/sgml/func.sgml | 166 +++++++++++++++++++++++++++++--------- doc/src/sgml/logicaldecoding.sgml | 2 +- doc/src/sgml/monitoring.sgml | 2 +- 4 files changed, 137 insertions(+), 41 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 89f3a7c1196..c2e42f31c00 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -198,6 +198,12 @@ PostgreSQL Log Sequence Number + + pg_snapshot + + user-level transaction ID snapshot + + point @@ -279,7 +285,7 @@ txid_snapshot - user-level transaction ID snapshot + user-level transaction ID snapshot (deprecated; see pg_snapshot) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 4d88b45e726..cc4a7bf8dfa 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -18998,6 +18998,38 @@ SELECT collation for ('foo' COLLATE "de_DE"); are stored globally as well. + + pg_current_xact_id + + + + pg_current_xact_id_if_assigned + + + + pg_current_snapshot + + + + pg_snapshot_xip + + + + pg_snapshot_xmax + + + + pg_snapshot_xmin + + + + pg_visible_in_snapshot + + + + pg_xact_status + + txid_current @@ -19031,76 +19063,136 @@ SELECT collation for ('foo' COLLATE "de_DE"); - The functions shown in + The functions shown in provide server transaction information in an exportable form. The main use of these functions is to determine which transactions were committed between two snapshots. - +
Transaction IDs and Snapshots Name Return Type Description + + + pg_current_xact_id() + xid8 + get current transaction ID, assigning a new one if the current transaction does not have one + + + pg_current_xact_id_if_assigned() + xid8 + same as pg_current_xact_id() but returns null instead of assigning a new transaction ID if none is already assigned + + + pg_xact_status(xid8) + text + report the status of the given transaction: committed, aborted, in progress, or null if the transaction ID is too old + + + pg_current_snapshot() + pg_snapshot + get current snapshot + + + pg_snapshot_xip(pg_snapshot) + setof xid8 + get in-progress transaction IDs in snapshot + + + pg_snapshot_xmax(pg_snapshot) + xid8 + get xmax of snapshot + + + pg_snapshot_xmin(pg_snapshot) + xid8 + get xmin of snapshot + + + pg_visible_in_snapshot(xid8, pg_snapshot) + boolean + is transaction ID visible in snapshot? (do not use with subtransaction IDs) + + + +
+ + + The internal transaction ID type xid is 32 bits wide and + wraps around every 4 billion transactions. However, these functions use a + 64-bit variant xid8 that does not wrap around during the life + 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 . + + + + In releases of PostgreSQL before 13 there was + no xid8 type, so variants of these functions were provided + that used bigint. These older functions with + txid in their names are still supported for backward + compatibility, but may be removed from a future + release. See . + + + + Transaction IDs and Snapshots (Deprecated Functions) + + + Name Return Type Description + + txid_current() bigint - get current transaction ID, assigning a new one if the current transaction does not have one + see pg_current_xact_id() txid_current_if_assigned() bigint - same as txid_current() but returns null instead of assigning a new transaction ID if none is already assigned + see pg_current_xact_id_if_assigned() txid_current_snapshot() txid_snapshot - get current snapshot + see pg_current_snapshot() txid_snapshot_xip(txid_snapshot) setof bigint - get in-progress transaction IDs in snapshot + see pg_snapshot_xip() txid_snapshot_xmax(txid_snapshot) bigint - get xmax of snapshot + see pg_snapshot_xmax() txid_snapshot_xmin(txid_snapshot) bigint - get xmin of snapshot + see pg_snapshot_xmin() txid_visible_in_snapshot(bigint, txid_snapshot) boolean - is transaction ID visible in snapshot? (do not use with subtransaction ids) + see pg_visible_in_snapshot() txid_status(bigint) text - report the status of the given transaction: committed, aborted, in progress, or null if the transaction ID is too old + see pg_xact_status()
- - The internal transaction ID type (xid) is 32 bits wide and - wraps around every 4 billion transactions. However, these functions - export a 64-bit format that is extended with an epoch counter - so it will not wrap around during the life of an installation. - The data type used by these functions, txid_snapshot, - stores information about transaction ID - visibility at a particular moment in time. Its components are - described in . - - - +
Snapshot Components @@ -19115,31 +19207,29 @@ SELECT collation for ('foo' COLLATE "de_DE"); xmin - Earliest transaction ID (txid) that is still active. All earlier - transactions will either be committed and visible, or rolled - back and dead. + Lowest transaction ID that was still active. All transaction IDs + less than xmin are either committed and visible, + or rolled back and dead. xmax - First as-yet-unassigned txid. All txids greater than or equal to this - are not yet started as of the time of the snapshot, and thus invisible. + One past the highest completed transaction ID. All transaction IDs + greater than or equal to xmax had not yet + completed as of the time of the snapshot, and thus are invisible. xip_list - Active txids at the time of the snapshot. The list - includes only those active txids between xmin - and xmax; there might be active txids higher - than xmax. A txid that is xmin <= txid < - xmax and not in this list was already completed - at the time of the snapshot, and thus either visible or - dead according to its commit status. The list does not - include txids of subtransactions. + Transactions in progress at the time of the snapshot. A transaction + ID that is xmin <= X < xmax and not in this + list was already completed at the time of the snapshot, and is thus + either visible or dead according to its commit status. The list does + not include the transaction IDs of subtransactions. @@ -19148,14 +19238,14 @@ SELECT collation for ('foo' COLLATE "de_DE");
- txid_snapshot's textual representation is + pg_snapshot's textual representation is xmin:xmax:xip_list. For example 10:20:10,14,15 means xmin=10, xmax=20, xip_list=10, 14, 15. - txid_status(bigint) reports the commit status of a recent + pg_xact_status(xid8) reports the commit status of a recent transaction. Applications may use it to determine whether a transaction committed or aborted when the application and database server become disconnected while a COMMIT is in progress. @@ -19169,7 +19259,7 @@ SELECT collation for ('foo' COLLATE "de_DE"); transactions are reported as in progress; applications must check pg_prepared_xacts if they - need to determine whether the txid is a prepared transaction. + need to determine whether the transaction ID belongs to a prepared transaction. diff --git a/doc/src/sgml/logicaldecoding.sgml b/doc/src/sgml/logicaldecoding.sgml index bce6d379bf0..bad3bfe6206 100644 --- a/doc/src/sgml/logicaldecoding.sgml +++ b/doc/src/sgml/logicaldecoding.sgml @@ -418,7 +418,7 @@ CREATE TABLE another_catalog_table(data text) WITH (user_catalog_table = true); Any actions leading to transaction ID assignment are prohibited. That, among others, includes writing to tables, performing DDL changes, and - calling txid_current(). + calling pg_current_xact_id(). diff --git a/doc/src/sgml/monitoring.sgml b/doc/src/sgml/monitoring.sgml index fd8b17ef8f6..c50b72137f3 100644 --- a/doc/src/sgml/monitoring.sgml +++ b/doc/src/sgml/monitoring.sgml @@ -1112,7 +1112,7 @@ postgres 27093 0.0 0.0 30096 2752 ? Ss 11:34 0:00 postgres: ser CLogTruncationLock - Waiting to execute txid_status or update + Waiting to execute pg_xact_status or update the oldest transaction id available to it. -- cgit v1.2.3