pg_controldata

Display control information for a specific data directory

$ pg_controldata [[-D|--pgdata]] [path/to/data]

$ pg_controldata [[-?|--help]]

$ pg_controldata [[-V|--version]]

pg_controldata [option...] [data_directory]
pg_controldata [-V | --version]
pg_controldata [-? | --help]

data_directory
    Specifies the path to the PostgreSQL data directory. If not provided, the value of the PGDATA environment variable is used.

-D directory
--pgdata=directory
    Explicitly sets the PostgreSQL data directory to use. This option overrides any value set by the PGDATA environment variable.

-V
--version
    Prints the pg_controldata version and exits.

-?
--help
    Shows help about pg_controldata command line arguments, then exits.

The pg_controldata command is a crucial utility for inspecting the control file of a PostgreSQL database cluster. The control file is a small, binary file located within the PGDATA directory (typically in PGDATA/global/pg_control) that stores vital, cluster-wide metadata. This metadata includes the PostgreSQL version, system identifier, WAL segment size, checkpoint location, current WAL file, last successful shutdown time, and the current state of the database (e.g., in recovery, shut down cleanly).

Unlike many other PostgreSQL utilities, pg_controldata operates directly on the data directory and does not require the PostgreSQL server to be running. This makes it an invaluable tool for diagnostics, troubleshooting, and understanding the state of a database cluster, particularly after a crash, for recovery planning, or when the server fails to start. It allows administrators to quickly ascertain critical details about the cluster's health and configuration without engaging the server process, which can be essential for debugging startup issues or verifying backup integrity.

The command must be executed by the operating system user that owns the PostgreSQL data directory (typically 'postgres') to ensure proper file permissions.

The output format of pg_controldata is primarily for human readability and is not guaranteed to be stable across different PostgreSQL versions. Scripting against its output is generally discouraged due to potential changes in field names or order.

This utility only reads the control file; it does not modify any data within the cluster.

If the control file itself is corrupted or missing, pg_controldata may fail to execute or display incorrect information.

The PGDATA environment variable can be set to specify the default PostgreSQL data directory. If this variable is set and no -D option or positional argument is provided, pg_controldata will use the path specified by PGDATA.

pg_controldata is an essential diagnostic tool for administrators. It is frequently used to quickly determine critical cluster parameters such as the PostgreSQL version, the system identifier (useful for checking compatibility with backups), the status of the last shutdown, and whether the cluster is currently in recovery. This information is crucial for troubleshooting startup failures, planning recovery operations, or verifying the integrity of a data directory.

The pg_controldata utility has been a fundamental part of the PostgreSQL distribution since its early versions, serving as a vital diagnostic tool. Its core functionality of reading and displaying the contents of the control file has remained consistent. Over time, as new features and capabilities were added to PostgreSQL (e.g., support for data checksums, improved recovery mechanisms), the control file structure evolved to store this additional metadata. Consequently, pg_controldata was updated to reflect and display these new fields, providing administrators with more comprehensive insights into the cluster's state. Its development is tightly coupled with the PostgreSQL project's overall evolution, ensuring it always provides relevant information for the current database version.

pg_ctl(1), pg_resetwal(1), initdb(1), psql(1)