With pgBackRest, what do the check and verify commands each prove about a stanza, and when would you run each?
answer
- live path versus stored bytes
- forced WAL switch, then wait
- re-read files against manifests
- WAL ranges expose gaps
- output defaults to none
basics
~20 spgBackRest check proves the live path works: it forces a WAL switch and waits for that segment to reach the repositories. verify proves stored data is intact: it rereads backups and archived WAL and compares sizes and checksums with the manifests.
solid answer
~40 s`check` tests the **live path**. It validates the stanza configuration and `archive_command`, then on the primary calls `pg_create_restore_point()` and `pg_switch_wal()` and waits up to `archive-timeout` (60 s by default) for the segment to arrive in the repositories. On a standby it can only test the repository side. `verify` tests **what is already stored**. It loads `archive.info`, `backup.info` and each backup manifest, rereads every backup file and archived WAL segment, and compares size and checksum. It also groups the WAL into continuous ranges, so a missing segment shows up as a gap. Its `--output` defaults to `none`, so read the log or pass `--output=text`. Run `check` after setup, after configuration or host changes, and as a cheap probe. Run `verify` per repository on a schedule, or with `--set` for one backup. Neither starts PostgreSQL.
code
bash · 8 lines# live path: config plus a forced WAL switch that must reach the repo
pgbackrest --stanza=analytics check
# stored data: every backup and WAL segment in repo2
pgbackrest --stanza=analytics --repo=2 --output=text verify
# one backup set before relying on it
pgbackrest --stanza=analytics --repo=1 --set=20261004-013002F --output=text --verbose verifygo deeper
Recall that check tests archiving and configuration now, while verify rereads stored backups and WAL against their checksums.
Explain how check forces a WAL switch and waits for it, and what verify compares: manifests, file sizes, checksums and WAL continuity.
Show operational use: verify each repository on a schedule, alert on its status rather than its silence, and use --set before trusting one backup.
Place check and verify within a broader assurance plan, with restore drills on top, and budget verify's full read of object storage.
## Two different questions pgBackRest ships two commands whose names sound alike but which answer different questions: | | `check` | `verify` | |---|---|---| | question | does archiving and configuration work **right now**? | are the backups and WAL **already stored** intact? | | touches PostgreSQL | yes, on the primary it forces a WAL switch | no, it reads only the repository | | catches | broken `archive_command`, wrong `pg1-path`, unreachable repository | missing files, truncated files, checksum mismatches, gaps in archived WAL | | cost | seconds | reads the whole repository, or one backup set with `--set` | ## What check does 1. It validates the stanza's configuration against the running cluster and each configured repository. 2. On the primary it calls `pg_create_restore_point('pgBackRest Archive Check')` and `pg_switch_wal()` to force a segment to be archived. 3. It waits up to `archive-timeout` (default 60 seconds) for that segment to appear in the repositories, and fails if it does not. 4. On a standby it cannot switch WAL, so it only tests the repository configuration. This is the misconfiguration that otherwise surfaces as a **backup that cannot complete**. An online backup also waits for the WAL it needs for consistency, and with a broken archive that WAL never arrives. ## What verify reads `verify` works through a repository (`--repo` selects one) without needing PostgreSQL running: - **Info files**: `archive.info` and `backup.info` and their `.copy` twins must load and agree with each other. Release 2.59 added further `backup.info` checks. - **Manifests**: each backup's manifest, falling back to its copy if the main file is unusable. - **Backup files**: every file a backup lists is read back, and its size and checksum are compared with the manifest. A diff or incr that references a file stored in its full inherits that file's result. - **Archived WAL**: every segment's checksum is checked, and segments are grouped into continuous ranges per archive id, so a hole in the WAL stream is visible. - **Scope**: `--set=<label>` limits the run to one backup set and the WAL it needs for consistency. ## Reading the result - Backups are reported as `valid`, `invalid` (a file is missing or failed a size or checksum test), `manifest missing` (often an expired backup) or `in-progress` (skipped). - The `output` option defaults to **`none`**, so the summary goes to the log. Pass `--output=text` to print it to the console, and `--verbose` to list what passed as well as what failed. - Alert on the reported `status`, not merely on whether the job ran. ## When to run each - `check`: after `stanza-create`, after any change to `archive_command`, hosts, paths or repositories, and as a frequent monitoring probe. - `verify`: on a schedule for **each** repository. On object storage it reads every object, so run it from a host close to the bucket and size `process-max` for it. - `verify --set`: after a suspicious event, before relying on one backup for a restore. ## A failure walkthrough Suppose a scheduled `verify` against repo2 of the analytics stanza reports `status: error`. The output tells you which kind of damage it found: 1. **Archived WAL split into two ranges** for one archive id: a segment is missing, so point-in-time recovery across that gap is impossible. Backups whose consistency WAL sits on either side can still be restored to their own end point. Check the `archive-push` logs (with async archiving, the `[stanza]-archive-push-async.log` file) for the window, and take a new backup so recovery can start after the gap. 2. **A backup marked `invalid` with checksum-invalid files**: the stored copy is damaged. Every diff or incr that references those files is invalid too. Restore from another backup or from the other repository, and investigate the storage. 3. **`manifest missing`** for a label: usually a backup that expire removed while verify was running, which is not damage. Because verify spreads its work across `process-max` processes, give it a higher value on a repository host than you would allow on the database host. ## What neither proves Neither command starts PostgreSQL or replays WAL, so neither shows that a restored cluster reaches consistency or holds the data you expect. That evidence comes from a restore drill, which the restore-testing topic covers. `info` is not a substitute either: it reports stanza status (`ok`, or `mixed` across repositories) and the WAL minimum and maximum, but it does not reread files.
- pgBackRest verify ran from cron and printed nothing. Does that mean every backup is valid?Not by itself. verify's `--output` defaults to `none`, so the console stays quiet either way, and the summary goes to the pgBackRest log. Run it with `--output=text`, or parse the log, and alert on the reported status: `error` with counts of missing, size-invalid and checksum-invalid files, or individual backups marked `invalid`.
- Why does pgBackRest check behave differently on a standby?check proves archiving by forcing a WAL switch with `pg_switch_wal()`, and a standby cannot switch WAL. On a standby, check therefore tests only the repository configuration. To prove the archive path, run it where the primary is reachable.
- pgBackRest check rereads every stored backup file to confirm its checksum.
- pgBackRest verify restores the backup into a scratch cluster and starts it.
- If verify prints nothing to the console, the repository is clean.
- Running verify against repo1 also covers the copy in repo2.
- A backup that check accepted can never fail verify later.