pg-witness

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.

See real runs $99 once, Linux amd64

$ 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
Recorded on Debian with Postgres 17. 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.

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.

  1. Checks the file starts with the custom-format header and hashes it.

    PGDMP magic, SHA-256
  2. Reads the archive table of contents. Object counts come from here.

    pg_restore --list shop.dump
  3. Makes sure the target is this machine and the server answers. A remote host is refused.

    pg_isready -t 3; psql -c 'SELECT 1'
  4. Creates an empty database with a random name.

    CREATE DATABASE "pgwitness_<12 hex>"
  5. Restores the whole dump into it and stops at the first error.

    pg_restore --exit-on-error -d pgwitness_… shop.dump
  6. 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_verifybackup territory.
  • 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 environment until 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

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"
Example script. 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.

ExitStatusMeaning
0okRestore finished with exit code 0 and the throwaway database was dropped.
1dump_badThe archive is unreadable, truncated, corrupt, or from a newer pg_dump than your pg_restore. Re-dump or fix the copy.
2environmentThis machine could not run the check: no server, no createdb rights, missing tools, role, or tablespace. Fix the machine and run again.
3errorAnything else, including a rejected format, a remote target, an unrecognised pg_restore failure, or a database that was not dropped.
4usageBad arguments. No evidence file is written.
dump_sha256
Hash of the file as read. Empty if it was never hashed.
restore_exit_code
pg_restore exit code, or null if 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

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_restore at least as new as the pg_dump that wrote the file. An older one rejects the archive, and that shows up as dump_bad with "unsupported archive version". WITH (FORCE) on the drop needs Postgres 13 or later; on older servers it falls back to a plain DROP 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-only from 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 --out or 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.