PostgreSQL Backup Verification Is Not a Restore Test: What pg_verifybackup Leaves Unproven
DATABASE RECOVERY
A verified backup is useful evidence. It is not the same evidence as a database that recovers to the intended state and supports the application.
By Hossam
The successful check and the unanswered question
A storage job completes, the backup files exist and verification reports success. Can the service now recover? That last question is broader than the checks already performed. It includes which backup was selected, what was checked, which recovery point is reachable and what the recovered application can actually do.
PostgreSQL 18 documents this boundary directly: pg_verifybackup cannot include every check that a running server will perform when using a backup. The documentation still calls for test restores and checking that the recovered databases work and appear to contain the correct data. Verification is valuable precisely because it catches problems early, not because it eliminates the next test.
This article follows the version-specific PostgreSQL 18 documentation. It is a documentation-based decision guide, not a tested recovery procedure or a production command recipe. No database, backup archive or recovery environment was created for this article.
Documentation: pg_verifybackup.
First identify which kind of backup you have
pg_verifybackup checks a physical cluster backup taken with pg_basebackup against the server-generated backup_manifest. Do not apply that description to every file called a PostgreSQL backup. pg_basebackup covers the cluster rather than selecting one database or table.
pg_dump creates a logical export of one database. Global objects such as roles and tablespaces require separate attention; the documentation points to pg_dumpall for those. Plain SQL scripts and non-plain archives also use different restore paths. pg_restore handles the non-plain archive formats produced by pg_dump.
The distinction matters for recovery promises. PostgreSQL explains that logical dumps do not contain the information needed for WAL replay and cannot be substituted for a physical base backup in a continuous-archiving recovery plan. A useful logical export can still be the wrong artifact for a particular point-in-time recovery objective.
Documentation: pg_verifybackup, pg_basebackup, pg_dump, pg_restore, Continuous Archiving and Point-in-Time Recovery.
What the manifest check actually covers
The documented verification sequence starts by reading and validating the manifest. A missing, unreadable or malformed manifest, an internal checksum failure or a system-identifier mismatch with the backup control data prevents that stage from succeeding.
The next stages compare the backup files with the manifest and check their recorded checksums. Missing or unexpected files, size differences and checksum mismatches can reveal storage damage or handling mistakes. But the scope has explicit exceptions. For example, postgresql.auto.conf, standby.signal and recovery.signal are ignored because backup preparation may legitimately change them. The file comparison also does not treat the contents of pg_wal as ordinary manifest-listed data files.
The final stage uses the required WAL ranges recorded in the manifest and invokes pg_waldump to parse them. This is stronger than merely seeing a directory of log files. It can expose missing records or obvious corruption. It still does not reproduce every action that server recovery will perform, and it does not check extra WAL beyond the ranges needed for that backup.
Record the actual options with the result. Skipping checksums removes content-checksum verification while retaining file presence and size checks. Skipping WAL parsing removes another layer. Ignoring a path suppresses checks for that path. A success message produced under narrower options should not be reported as though all checks ran.
Documentation: pg_verifybackup, Backup Manifest Format.
Version and format change the meaning of success
In the PostgreSQL 18 documentation, pg_verifybackup supports plain and tar backup formats, including supported compressed tar formats. However, WAL verification is supported only for plain-format backups. The documented tar path therefore skips WAL parsing. A successful tar integrity check under that limitation is not evidence that WAL parsing also passed.
WAL verification is version-specific: the verifier and its pg_waldump must match the backup being checked. The documentation distinguishes this from the data-file integrity checks, which should work across server versions that generate a backup manifest. Keep the backup version, tool version, format and options in the same evidence record rather than saving only the final status line.
Incremental backups add a dependency boundary. PostgreSQL 18 says an incremental backup cannot be used directly. It must be combined with the previous backups on which it depends using pg_combinebackup. Keeping the latest incremental file while removing a required earlier backup does not preserve a usable recovery chain.
Documentation: pg_verifybackup, pg_basebackup, Continuous Archiving and Point-in-Time Recovery.
Required backup WAL is not every later recovery point
A base backup needs the WAL required to make that backup usable. Recovering to a later point through continuous archiving needs an appropriate continuous WAL sequence as well. PostgreSQL specifies that the archived sequence must extend back at least as far as the start of the base backup.
That creates two different coverage questions: did verification parse the WAL needed for this backup, and can the retained archive support the later target the business expects? The first answer cannot silently stand in for the second. Name the intended recovery target and test the corresponding path.
Configuration also lives across this boundary. WAL replay does not restore manually edited changes to postgresql.conf, pg_hba.conf or pg_ident.conf. Those files need an appropriate backup arrangement. The recovered data state and the configuration needed to run it are related, but they are not identical evidence.
Documentation: pg_verifybackup, Continuous Archiving and Point-in-Time Recovery.
A checksum is not an independent witness
pg_basebackup offers several manifest checksum algorithms. PostgreSQL 18 documents CRC32C as the default and distinguishes its ability to catch accidental changes from the adversarial protection offered by cryptographic SHA digests.
Even a cryptographic digest needs a trustworthy comparison point. The documentation warns that, against an adversary who can change the backup, the manifest must be stored securely elsewhere or otherwise verified not to have changed. If someone replaces both the files and the record you compare them with, agreement alone is not independent evidence of authenticity.
This does not make checksums pointless. It means that storage-integrity checking and protection of the reference evidence solve different problems. Keep both in the recovery design.
Documentation: pg_basebackup.
Rehearse the recovery, not just the command
A useful rehearsal starts with an isolated destination and an explicit acceptance plan. Isolation is an editorial safety recommendation here, not a claim that a separate database name alone makes a restore safe. Paths, tablespaces, credentials and any application connections also need review before running the real procedure.
PostgreSQL warns about concrete path risks: tablespaces can use absolute locations, and replaying tablespace creation can affect those locations even when the data directory is different. Follow the version-specific recovery documentation with someone responsible for the environment. Do not improvise a destructive restore against the only copy of data.
The documented recovery procedure ends with inspecting the contents to confirm the desired state before ordinary users reconnect. For an application team, translate that into explicit checks appropriate to the service: expected schemas, selected known records, the intended recovery point and representative application queries. These examples are acceptance criteria to design, not a universal PostgreSQL test suite.
Time the rehearsal and record what was included. Downloading the archive, obtaining access, preparing storage, replaying logs and validating the application can all matter to service restoration. A measured rehearsal duration is an observation under those conditions, not a guarantee that the next incident will take the same time.
Documentation: pg_basebackup, Continuous Archiving and Point-in-Time Recovery.
A fictional review with three different outcomes
Imagine Cedar keeps a physical backup, a manifest and archived WAL. This is a fictional review, not output from a real system. The team checks the backup files against the manifest and gets no reported errors. It then discovers that the run skipped WAL parsing. The supported conclusion is narrower than complete verification: the recorded file checks passed; the omitted WAL check remains unperformed.
In a second rehearsal, the required backup WAL is available and recovery starts. The team wants a later target, but its archive has a gap before that point. Verification of the base backup did not establish that later recovery objective.
In a third rehearsal, PostgreSQL recovers and accepts connections. The application cannot perform a required operation under its intended role. That is not proof that file verification lied. It is evidence that file integrity, server recovery and application acceptance answer different questions. Keep the failed acceptance result visible instead of allowing an earlier green check to overwrite it.
Documentation: pg_verifybackup, Continuous Archiving and Point-in-Time Recovery.
Logical archives need their own acceptance checks
For a logical archive, pg_restore can list its table of contents. A readable object list is useful preparation, but it is not a trial restoration of those objects and their data. Inspect the restore result, not just the ability to list what the archive says it contains.
Error handling also matters: PostgreSQL 18 documents that pg_restore normally continues after SQL errors and reports an error count at the end; an exit-on-error option changes that behavior. Read the diagnostics and decide what constitutes a failed rehearsal before running it.
Restoring a dump is also a trust decision. PostgreSQL warns that it can execute code chosen by the source superusers, and a partial restore does not remove that risk. A dump from an untrusted source requires inspection and an appropriate security boundary, not casual restoration into a privileged environment.
Documentation: pg_dump, pg_restore.
Keep a recovery evidence record
For the next review, keep the artifact identity, backup type, source and tool versions, format, manifest protection, options used, WAL scope and required dependencies together. Add the intended target, isolated restore destination, recovery result, data checks and application acceptance result.
Use separate statuses for separate claims: files checked, required WAL parsed, target reached and application accepted. Include failures and omitted checks. That record makes the next decision easier because it says what was actually demonstrated.
The goal is not to replace a precise tool with a vague manual exercise. It is to combine precise integrity checking with an equally explicit recovery rehearsal, without pretending either proves more than it does.
Documentation: pg_verifybackup, pg_basebackup, Continuous Archiving and Point-in-Time Recovery.
Related: content identity has a boundary too
Our container image digests, signatures and provenance guide examines a similar distinction in artifact delivery: identifying unchanged content is not the same as establishing who produced it or whether it meets the intended policy. The systems differ; the habit of naming each piece of evidence transfers.
Sources and scope
- PostgreSQL 18: pg_verifybackup
- PostgreSQL 18: pg_basebackup
- PostgreSQL 18: Continuous Archiving and Point-in-Time Recovery
- PostgreSQL 18: pg_dump
- PostgreSQL 18: pg_restore
- PostgreSQL 18: Backup Manifest Format
Based on the official PostgreSQL 18 documentation, reviewed 20 November 2026. Version-specific behavior is not a claim about every PostgreSQL release. No hands-on backup, restore, benchmark or production test was performed. Cedar and its review outcomes are fictional. Recovery acceptance examples are editorial guidance, not a substitute for your version-specific runbook and responsible operator.
Comments
Post a Comment