Prove your Postgres backup restores before the day you need it.
A Linux CLI that restores your pg_dump -Fc file into a throwaway local database and writes a JSON record of the test: the dump's SHA-256, when it ran, and whether it restored. Keep it next to the backup. Hand it over when an auditor, a client, or your boss asks.
$ pg_dump -Fc -d shop -f shop.dump $ pg-witness verify --dump shop.dump --out evidence.json pg-witness: status=ok $ echo $? 0 $ head -c 150000 shop.dump > shop-cut.dump $ pg-witness verify --dump shop-cut.dump --out shop-cut.json pg-witness: status=dump_bad pg-witness: archive unreadable or truncated pg-witness: detail: pg_restore: error: could not read from input file: end of file $ echo $? 1
shop-cut.dump is the first 150,000 of 312,901 bytes, which is what a half-finished copy leaves behind.When someone asks whether your backups restore
Security questionnaires, SOC 2 and ISO 27001 audits, and client contracts often ask for proof that backups are restore-tested. 'Our cron job runs pg_restore' is a claim. An evidence file is a record.
- Names the exact file it tested, by SHA-256.
- Says when: start and finish timestamps.
- Says what happened: status, the pg_restore exit code, and the first Postgres error if there was one.
- Has the same fields on every run, described in a published JSON Schema, so a month of files can be collected and checked.
pg-witness does not make you compliant. It gives you the restore-test record those reviews ask for.
What one run does
Everything happens on the machine you run it on. These are the commands it calls, in order. If any step fails, it stops there and says which kind of failure it was.
-
Checks the file starts with the custom-format header and hashes it.
PGDMP magic, SHA-256 -
Reads the archive table of contents. Object counts come from here.
pg_restore --list shop.dump -
Makes sure the target is this machine and the server answers. A remote host is refused.
pg_isready -t 3; psql -c 'SELECT 1' -
Creates an empty database with a random name.
CREATE DATABASE "pgwitness_<12 hex>" -
Restores the whole dump into it and stops at the first error.
pg_restore --exit-on-error -d pgwitness_… shop.dump -
Drops the database, even after a failed restore. A failed drop is written into the evidence.
DROP DATABASE … WITH (FORCE)
The cut file above is why step 5 exists. The table of contents sits at the front of the archive, so pg_restore --list shop-cut.dump exits 0 on it. Only a real restore reaches the missing bytes.
What each exit code means is listed under Exit codes and the evidence format.
Real runs, unedited
Each block is the JSON file the CLI wrote, copied as is from runs on the same machine. Timestamps are UTC because that box runs in UTC.
status: ok, exit 0. The full restore of shop.dump above.{
"dump_sha256": "871c30b322ee8466ca40bcbbfe17ec18a5b1a07cbe4f5e5cd298a9d386cb5ca1",
"format": "custom",
"started_at": "2026-10-09T18:43:07.445848755Z",
"finished_at": "2026-10-09T18:43:07.669203013Z",
"duration_ms": 223,
"restore_exit_code": 0,
"object_counts": {
"constraints": 3,
"defaults": 2,
"fk_constraints": 1,
"indexes": 1,
"sequence_owned_by": 2,
"sequence_set": 2,
"sequences": 2,
"table_data": 2,
"tables": 2,
"views": 1
},
"status": "ok",
"reasons": []
}
dump_bad, exit 1. The cut file. The TOC still reads, so counts are present; the restore failed with exit code 1."restore_exit_code": 1, "status": "dump_bad", "reasons": [ "archive unreadable or truncated", "detail: pg_restore: error: could not read from input file: end of file" ]
dump_bad, exit 1. The same dump cut to 2,000 bytes, inside the TOC. It fails at --list, so no database is created."restore_exit_code": null,
"object_counts": {},
"status": "dump_bad",
"reasons": [
"archive unreadable or truncated",
"detail: pg_restore: error: could not read from input file: end of file"
]
environment, exit 2. A good dump whose tables belong to a role this server does not have."restore_exit_code": 1, "status": "environment", "reasons": [ "role does not exist", "detail: pg_restore: error: could not execute query: ERROR: role \"app_owner\" does not exist" ]
The three short blocks are excerpts. Their full files have the same fields as the ok one.
What it checks, and what it leaves to you
Checks
- The file is a custom-format archive and its TOC can be read.
- Every entry restores into an empty database with
--exit-on-error, on your server version. - Whether a failure came from the archive or from your machine (missing role, tablespace, rights, or tools).
- The SHA-256 of the exact file it tested, so the evidence points at one file.
- The throwaway database was dropped afterwards.
Does not check
- That the data is the data you expected. Counts are TOC entries, not row counts, and nothing is compared with production.
- Physical backups, WAL archives, or point-in-time recovery. That is
pg_verifybackupterritory. - Plain SQL (
-Fp) or directory (-Fd) dumps. Both are rejected. - Remote servers. Only a Unix socket,
localhost,127.0.0.1, or::1. - Roles. It does not create them, so a dump that needs them reports
environmentuntil they exist.
Compared with a script you write yourself
You can build this. The core is createdb, pg_restore --exit-on-error, and dropdb, and you may already have that in a cron job. If yours drops the database after a failed restore, tells a missing role apart from a broken archive, refuses to point at a remote host, and writes the same output every time, keep it.
pg-witness is that script done once, with the edge cases above handled and the output written down as a contract. You pay $99 so you don't have to maintain it, and so the record looks the same every night.
pg_restore --list on its own is not a restore test. The cut file in the first example lists cleanly. pg_verifybackup checks physical base backups, which are a different artifact from a logical dump. A pass on one says nothing about the other.
$99, once
One evidence file per backup, for as long as you run it.
Checkout is closed right now. Email me when checkout opens
- The Linux amd64 binary, delivered as a one-time download link after payment. The link works once and expires.
- No subscription, license key, or seat count.
- 14-day money-back refund. Email us or go through Paddle. See the refund policy.
- Paddle is the merchant of record. Your payment and receipt go through Paddle.
Using it in a restore drill
Run it right after the backup job, on a machine with the same Postgres major version you would restore onto. Keep the evidence file next to the dump. When someone asks whether last night's backup restores, you hand them a file with the dump's hash, the time of the test, and the result.
To run the same drill by hand with pg_restore, see How to test that a pg_dump backup restores.
A non-zero exit is your alert. Something like this in the backup script is enough:
f=/backups/app-$(date +%F).dump pg_dump -Fc -d app -f "$f" pg-witness verify --dump "$f" --out "$f.evidence.json" || notify "restore check failed: $f"
notify stands in for whatever pages you.The restore uses a full copy of the database, so the machine needs disk for one extra copy while it runs. It takes about as long as a pg_restore of the same file would.
Exit codes and the evidence format
There is no trial, so here is the contract instead. Scripts can branch on the exit code alone. The JSON fields are fixed for v1 and described in a published JSON Schema.
| Exit | Status | Meaning |
|---|---|---|
| 0 | ok | Restore finished with exit code 0 and the throwaway database was dropped. |
| 1 | dump_bad | The archive is unreadable, truncated, corrupt, or from a newer pg_dump than your pg_restore. Re-dump or fix the copy. |
| 2 | environment | This machine could not run the check: no server, no createdb rights, missing tools, role, or tablespace. Fix the machine and run again. |
| 3 | error | Anything else, including a rejected format, a remote target, an unrecognised pg_restore failure, or a database that was not dropped. |
| 4 | usage | Bad arguments. No evidence file is written. |
dump_sha256- Hash of the file as read. Empty if it was never hashed.
restore_exit_codepg_restoreexit code, ornullif the run stopped before the restore.object_counts- TOC entries by type, from
pg_restore --list. reasons- Short causes, plus a
detail:line with the first Postgres error, cut at 400 characters.
Requirements
- Host
Linux on amd64
- Tools on
PATHpg_restore,psql, andpg_isreadyif you leave out--pg-uri. Same major version as the dump, or newer. - Server
A local Postgres where your login can
CREATE DATABASE. The CLI does not start one or bundle one. - Input
A custom-format dump from
pg_dump -Fc.
FAQ
- Does the dump leave my machine?
- No. There is no upload path and no telemetry. The CLI refuses any Postgres target that is not on the same machine.
- Is the evidence file enough for an audit?
- It is a record of one restore test: which file, when, and the result. Whether that satisfies a specific control is up to your auditor. Most want to see tests run on a schedule, so keep the file from every run.
- Does it phone home or need a license key?
- No. There is no license server and no seat check in the binary.
- Which Postgres versions?
- Whatever your local tools and server are. Use a
pg_restoreat least as new as thepg_dumpthat wrote the file. An older one rejects the archive, and that shows up asdump_badwith "unsupported archive version".WITH (FORCE)on the drop needs Postgres 13 or later; on older servers it falls back to a plainDROP DATABASE. - My dump restores fine elsewhere. Why
environment? - Usually a role or tablespace the dump references does not exist on this server. Create the roles first (
pg_dumpall --roles-onlyfrom the source is the usual way) and run it again. - Can it touch my other databases?
- It creates one database named
pgwitness_plus 12 random hex characters, restores into that, and drops it. It does not write to any other database. - Can I run it in cron or CI?
- Yes. Exit codes are stable and the JSON goes to
--outor stdout. Status lines go to stderr. - Why is there no trial?
- The binary has no license check, so a trial copy would be the full product. Instead, this page shows what it runs and what it writes, and every purchase has a 14-day refund.
- Mac or Windows?
- Not for sale. Linux amd64 only.
- Who makes it?
- Aabishkar Aryal, one developer. Questions go to support@pgwitness.com.