pg_verifybackup

Verify a backup stored in a specific directory

$ pg_verifybackup [path/to/backup]

$ pg_verifybackup [[-P|--progress]] [path/to/backup]

$ pg_verifybackup [[-e|--exit-on-error]] [path/to/backup]

$ pg_verifybackup [[-i|--ignore]] [path/to/file_or_directory] [path/to/backup]

$ pg_verifybackup [[-m|--manifest-path]] [path/to/backup_manifest] [path/to/backup]

$ pg_verifybackup [[-?|--help]]

pg_verifybackup [OPTION]... BACKUP_DIRECTORY

--help, -?
    Show help message and exit.

--version, -V
    Show version information and exit.

--exit-on-error, -e
    Exit immediately upon the first error encountered, rather than continuing to check other files.

--progress, -P
    Display a progress bar during the verification process, showing the current file being processed.

--progress-interval=MILLISECONDS, -S MILLISECONDS
    Report progress at the specified interval in milliseconds. Setting it to 0 disables progress reporting.

--skip-unreadable-files, -s
    Skip over files that cannot be read (e.g., due to insufficient permissions) instead of reporting an error for them.

--verbose, -v
    Enable verbose output, providing more detailed information about the verification process.

pg_verifybackup is a utility designed to check the structural integrity and data consistency of a PostgreSQL base backup. It systematically reads through all files within a specified backup directory, validating that data pages contain correct block numbers and Log Sequence Numbers (LSNs). If page checksums were enabled on the original PostgreSQL cluster, pg_verifybackup also verifies these checksums, ensuring data has not been corrupted since the backup was taken.

Beyond data files, it checks the timeline history files for correctness and confirms the presence of recovery.signal or standby.signal, which are crucial for subsequent recovery. This command serves as a proactive measure to ensure that a backup is viable for restoration, catching potential issues like file corruption or incomplete backups before they become critical during a disaster recovery scenario. It does not perform a full recovery or WAL replay, but rather focuses on the physical and structural soundness of the backup.

pg_verifybackup primarily focuses on the physical integrity of data pages and file structure. It does not verify the logical consistency of the backup (e.g., that all expected tables are present or that data content is logically correct). It also does not verify the integrity of Write-Ahead Log (WAL) files in the pg_wal subdirectory; these are checked during actual recovery. Furthermore, it ignores symbolic links that point outside the backup directory and only verifies files that are expected to contain PostgreSQL data.

The tool verifies relation files, checking for correct block numbers, LSNs, and checksums (if enabled). It also examines pg_control, postgresql.auto.conf, pg_wal/timeline files, and the presence of recovery.signal or standby.signal.

By default, pg_verifybackup attempts to check all files and reports all errors found. The --exit-on-error option can be used to stop at the first error.

The pg_verifybackup utility was introduced in PostgreSQL 13, providing a dedicated tool for pre-checking the integrity of base backups, enhancing the reliability of disaster recovery preparedness.

pg_basebackup(1), pg_checksums(1), pg_restore(1), initdb(1)