pg_control

A file containing information about the PostgreSQL server's internal state

pg_control is an 8kb binary file which stores information about various aspects of the PostgreSQL server's internal state, such as the most recent checkpoint, as well as fundamental parameters set by initdb. It is located in the cluster's global/ directory.

pg_control was first added in PostgreSQL 7.1 (commit 4d14fe00).

The contents of the pg_control file can be displayed by the client utility pg_controldata (and also pg_resetwal with the -n/--dry-run option). From PostgreSQL 9.6 (commit dc7d70ea), the following SQL functions can also be used to extract information from the file:

Source code

The name of the pg_control file is defined by XLOG_CONTROL_FILE in src/include/access/xlog_internal.h.

The structure of the pg_control file is defined by the struct ControlFileData, contained in the header file src/include/catalog/pg_control.h, even though it is not a heap relation.

The size of the pg_control file is defined by PG_CONTROL_FILE_SIZE (also in src/include/catalog/pg_control.h; PostgreSQL 9.6 and earlier: PG_CONTROL_SIZE), currently 8192 bytes. However the actual contents (as defined by the struct ControlFileData) are meant to occupy no more than 512 bytes to fit within typical disk drive sectors; see comment in src/include/catalog/pg_control.h. The file is zero-padded to reduce the likelihood of premature-EOF errors (see comment in src/backend/access/transam/xlog.c, function WriteControlFile()).

Format changes

The format of the pg_control file can change from one release to the next. This is a list of changes to the ControlFileData and CheckPoint structs since PostgreSQL 9.4.

PostgreSQL 12:

Following field added:

  • int max_wal_senders; (commit ea92368c)

Following fields removed:

  • uint32 nextXidEpoch; /* higher-order bits of nextXid */
  • TransactionId nextXid; /* next free XID */

and replaced by:

  • FullTransactionId nextFullXid; /* next free full transaction ID */

(commit 2fc7af5e)

PostgreSQL 11:

Removed following field:

  • XLogRecPtr prevCheckPoint; (commit 4b0d28de)

PostgreSQL 10:

Added following field:

  • char mock_authentication_nonce[MOCK_AUTH_NONCE_LEN]; (commit 818fd4a6)

PostgreSQL 9.5

Added following field:

  • bool track_commit_timestamp;

Additionally the CheckPoint struct had following fields added:

  • TransactionId oldestCommitTsXid; /* oldest Xid with valid commit timestamp */
  • TransactionId newestCommitTsXid; /* newest Xid with valid commit timestamp */

(All changes in commit 73c986ad; note PG_CONTROL_VERSION was not advanced until 99dd8b0)

PostgreSQL 9.4

Added following field:

  • int max_worker_processes; (commit 6bc8ef0b)

Restoring pg_control

In the unlikely event pg_control becomes corrupted, it might be possible to restore it using pg_resetwal (PostgreSQL 9.6 and earlier: pg_resetxlog).

Categories

PostgreSQL internals

See also

pg_controldata