Knowledge base · Backups

Verified restores explained

What the weekly verification actually does, what each check means, why a verification can fail, and what the badge shows.

A backup you've never restored is just a hope. Verification is VaultKeep restoring your backup, for real, on a schedule, and telling you what happened.

When it runs

Every Sunday, in the hour after your backup window, for every active project that has weekly verification enabled and at least one successful database backup. You can also click Verify on any successful backup to run one immediately.

What it does

1. Downloads the latest database backup from wherever it lives (managed storage or your own destination).
2. Checks integrity: the ciphertext SHA-256 must match what was recorded at backup time; then the artifact is decrypted (AES-256-GCM, which fails loudly on any tampering) and the plaintext SHA-256 must match the manifest.
3. Boots a throwaway Postgres cluster of the same major version inside the isolated job runner.
4. Runs a full pg_restore of the backup into it, capturing every error.
5. Compares with the manifest captured at backup time:

• every table must exist (table_count);
• tables with exact counts in the manifest must restore with exactly that many rows (row_counts);
• tables with estimated counts must be within ±10% (estimate_sanity);

1. Destroys the cluster and records the checks with the result.

Reading the result

On the project page each backup shows its verifications with a passed or failed badge; expand one to see every check with expected and actual values. A failed verification emails owners and admins and turns the public badge red.

Typical reasons for a failure:

• the backup was taken with a role that couldn't read some tables (row counts short);
• an extension needed by the schema isn't available in the verification cluster (restore errors);
• the backup file was corrupted in storage (integrity check);
• a very large table's estimate drifted more than 10% between backup and restore (usually harmless; run it again).

Treat a failed verification as "this backup is unreliable until the next one passes", and check the next backup and verification.

The badge

Each project can expose a public SVG badge at https://vaultkeep.dev/badge/<token>.svg:

• green: restore verified · N days ago
• red: restore verified · check failing
• grey: no verification yet or badge disabled

It reveals only the verification status and recency, never names, data or credentials. The URL contains an unguessable token; you can disable the badge or rotate the token under the project's Status badge tab. Put it in your README:

[![restore verified](https://vaultkeep.dev/badge/<token>.svg)](https://vaultkeep.dev)

Still stuck? Email support@vaultkeep.dev with your project name (never your connection string) and we'll take a look.