5.4. Commit Log (clog)

PostgreSQL maintains transaction statuses in the Commit Log, commonly referred to as the clog. The clog is allocated within shared memory and is utilized throughout all transaction processing.

This section describes the transaction states, the operation of the clog, and its maintenance.

Section Contents

5.4.1 Transaction Status

PostgreSQL defines four transaction states: IN_PROGRESS, COMMITTED, ABORTED, and SUB_COMMITTED.

The first three states are self-explanatory. For instance, while a transaction is active, its status is IN_PROGRESS.

SUB_COMMITTED is reserved for sub-transactions; its details are omitted from this documentation.

5.4.2. How Clog Performs

The clog consists of one or more 8 KB pages in shared memory. Logically, it forms an array where the indices correspond to transaction IDs (txids). Each entry in the array stores the status of the corresponding txid. Figure 5.7 illustrates the structure and operation of the clog.

Figure 5.7. How the clog operates.
  • T1: txid 200 commits; its status changes from IN_PROGRESS to COMMITTED.
  • T2: txid 201 aborts; its status changes from IN_PROGRESS to ABORTED.

As the current txid advances, PostgreSQL appends a new page whenever the current page is filled.

To perform concurrency control, internal functions retrieve the transaction status from the clog. These functions then return the state of the requested transaction. (Refer to “Hint Bits” in Section 5.7.1.1 for further details.)

5.4.3. Maintenance of the Clog

PostgreSQL writes clog data to files in the pg_xact1 subdirectory during shutdown or whenever a checkpoint process runs. These files are named sequentially, such as ‘0000’ and ‘0001’.

The maximum size for each file is 256 KB. For example, if the clog occupies eight pages (totaling 64 KB), the data is written entirely into file 0000. If the clog occupies 37 pages (totaling 296 KB), the data is distributed between 0000 (256 KB) and 0001 (40 KB).

During startup, PostgreSQL loads the data from the pg_xact files to initialize the clog in shared memory.

The total size of the clog increases continuously as new pages are appended. However, old data eventually becomes unnecessary. The vacuum process, described in Chapter 6, regularly removes obsolete clog pages and files. Details regarding the removal of clog data are provided in Section 6.4.

  1. Note: “pg_xact” was named “pg_clog” in versions 9.6 and earlier. ↩︎