F.13. csn — Commit Sequence Number Extension#

F.13. csn — Commit Sequence Number Extension

F.13. csn — Commit Sequence Number Extension
Prev	Up	Appendix F. Additional Supplied Modules and Extensions	Home	Next

F.13. csn — Commit Sequence Number Extension #

F.13.1. Overview
F.13.2. Rationale
F.13.3. Installation
F.13.4. Quickstart
F.13.5. Functions
F.13.6. Usage
F.13.7. Sample Output
F.13.8. Returned Values
F.13.9. Numeric Representation of CSN Values
F.13.10. Limitations
F.13.11. Compatibility

Version: 1.0

F.13.1. Overview #

The csn extension provides functions for retrieving the Commit Sequence Number (CSN) associated with transactions and snapshots. A CSN is a monotonically increasing identifier assigned at transaction commit time, enabling a total ordering of committed transactions.

This extension is intended for distributions that implement CSN-based MVCC. It is primarily useful for diagnostics, debugging, and visibility analysis.

F.13.2. Rationale #

Traditional XID based MVCC relies on transaction IDs (XIDs) and snapshots to determine visibility. CSN-based MVCC enhances this model by assigning a global commit order, simplifying visibility checks and reducing contention in highly concurrent environments.

The csn extension exposes this functionality to SQL, allowing users to:

Inspect commit ordering of transactions.
Analyze snapshot visibility boundaries.
Debug concurrency behavior.
Perform research on CSN-based MVCC systems.

F.13.3. Installation #

To install the extension, ensure that it has been compiled and installed into extension directory. Then enable it in the desired database:

CREATE EXTENSION csn;

To remove the extension:

DROP EXTENSION csn;

F.13.4. Quickstart #

Retrieve the CSN of the current transaction:

SELECT pg_csn(pg_current_xact_id());

Retrieve the CSN associated with the current snapshot:

SELECT pg_snapshot_csn(pg_current_snapshot());

Legacy-compatible interfaces:

SELECT txid_csn(txid_current());
SELECT txid_snapshot_csn(txid_current_snapshot());

F.13.5. Functions #

Function	Return Type	Description
`pg_csn(xid xid8)`	`bigint`	Returns the CSN of a transaction.
`pg_snapshot_csn(snapshot pg_snapshot)`	`bigint`	Returns the CSN corresponding to a snapshot.
`txid_csn(xid bigint)`	`bigint`	Compatibility wrapper for `pg_csn`.
`txid_snapshot_csn(snapshot txid_snapshot)`	`bigint`	Compatibility wrapper for `pg_snapshot_csn`.

Modern applications should prefer the pg_* functions.

F.13.6. Usage #

F.13.6.1. Example: Retrieve CSN of the Current Transaction #

SELECT pg_csn(pg_current_xact_id());

F.13.6.2. Example: Retrieve CSN of a Snapshot #

SELECT pg_snapshot_csn(pg_current_snapshot());

F.13.6.3. Example: Determine Commit Order #

BEGIN;
INSERT INTO test VALUES (1);
COMMIT;

SELECT pg_csn(pg_current_xact_id());

F.13.6.4. Legacy Compatibility #

SELECT txid_csn(txid_current());
SELECT txid_csn(txid_current() - 4);
SELECT txid_snapshot_csn(txid_current_snapshot());

F.13.7. Sample Output #

 pg_csn
--------
      42

Snapshot example:

 pg_snapshot_csn
-----------------
              42

Special values:

 pg_csn
--------
       3

This corresponds to CSN_FROZEN.

 pg_csn
--------
       0

This corresponds to CSN_INPROGRESS.

F.13.8. Returned Values #

All functions return a Commit Sequence Number (CSN) of type bigint. The result depends on the transaction's state and age.

Returned Value	Description
Normal CSN (≥ 4)	Indicates a successfully committed transaction.
`CSN_FROZEN`	Returned for bootstrap, frozen, or very old committed transactions.
`CSN_ABORTED`	Indicates that the transaction was aborted.
`CSN_INPROGRESS`	Indicates that transaction is in progress.
`CSN_COMMITTING`	Indicates that transaction is commiting now.

For transactions older than TransactionXmin, the CSN may no longer be stored in pg_csnlog. In such cases, the status is derived from pg_xact, and committed transactions return CSN_FROZEN.

TransactionXmin is the oldest xmin among all active backends, it is the system-wide MVCC horizon ensuring safe truncation of global metadata such as pg_subtrans and pg_csnlog.

F.13.9. Numeric Representation of CSN Values #

CSNs are represented as unsigned 64-bit integers.

Constant	Numeric Value	Description
`CSN_INPROGRESS`	0	Transaction is still in progress.
`CSN_ABORTED`	1	Transaction was aborted.
`CSN_COMMITTING`	2	Transaction is committing (internal use).
`CSN_FROZEN`	3	Frozen or very old committed transaction.
`CSN_FIRST_NORMAL`	4	First valid CSN assigned to a committed transaction.
`CSN_MAX_NORMAL`	2⁶³ − 1	Maximum valid CSN in normal operation.

F.13.10. Limitations #

The extension requires a build that supports CSN-based MVCC.
It is not supported without CSN infrastructure.
Arithmetic operations on xid8 are not supported in SQL.
Internal CSN states such as CSN_INPROGRESS are not exposed to users.
Results depend on the availability of CSN logs (pg_csnlog).

F.13.11. Compatibility #

Modern interfaces:

pg_csn(xid8)
pg_snapshot_csn(pg_snapshot)

Legacy compatibility interfaces:

txid_csn(bigint)
txid_snapshot_csn(txid_snapshot)

Prev	Up	Next
F.12. credcheck — Tantor SE username/password checks	Home	F.14. cube — a multi-dimensional cube data type