Consent Docs
Open console

Test a restore

Restore a backup into a throwaway database, and check its rows, evidence anchors and audit log chains against your recovery targets.

How-to2 min readFor project administrators and deployment operators

Test a restore on a schedule, such as once a month, and after any change to how you back up. scripts/restore-check.sh restores a backup into a throwaway database, checks it and drops it. It never writes to the live database.

Set your recovery targets#

The two targets are statements you make. The check tests both on every run.

Setting Default The check fails when
RECOVERY_POINT_HOURS 24 The backup is older than this. It is the most data you accept to lose.
RECOVERY_TIME_MINUTES 60 The restore takes longer than this.

Set them to what you tell your customers. Take backups at least as often as the recovery point.

Run the check#

Run it on a Linux host with the PostgreSQL client tools, in a checkout of the repository where server/node_modules is installed.

  1. Set the database variables as for the backup. The account must be allowed to create and drop databases.

  2. Set the API's key variables: EVIDENCE_CHAIN_KEYS or ENCRYPTION_KEY, and RECEIPT_SIGNING_PRIVATE_KEY or RECEIPT_SIGNING_KEY. The check verifies with them.

  3. If the database runs in a container, set RESTORE_CHECK_DB_HOST and RESTORE_CHECK_DB_PORT to where this host reaches it, such as 127.0.0.1 and 5436.

  4. Run the script with the backup.

    Shell
    RESTORE_CHECK_DATABASE=consent_check scripts/restore-check.sh \
  backups/piedap-consent-piedap_consent-20261009T013000Z.dump

  5. Read the result. A good run ends with Restore check passed. A failed one lists each problem and exits with status 1.

What it checks#

  1. The dump matches its SHA-256.
  2. The backup is younger than the recovery point.
  3. It restores into a new database within the recovery time.
  4. Every table has the rows the backup counted in its snapshot.
  5. The audit log still refuses changes and deletions.
  6. The latest 20 evidence anchors verify, with the API's own code.
  7. Every project's audit log chain verifies.
ok    SHA-256 of the dump
ok    the backup is 3 h old (target 24 h)
ok    restored into consent_check in 41 s (target 60 min)
ok    row counts of 51 tables match the backup
ok    the audit log is append-only in the restored database
ok    the latest 20 evidence anchors verify
ok    3 audit log chains verify (48210 entries)
Restore check passed

Choose what it does#

Setting Effect
RESTORE_CHECK_DATABASE The throwaway database's name, in lower-case letters, digits and underscores. The default adds the time to piedap_consent_restore_check_. The live database's name is refused.
RESTORE_CHECK_ANCHORS How many of the latest anchors to verify. Default 20.
RESTORE_CHECK_KEEP true keeps the database for a closer look. Drop it yourself afterwards.
RESTORE_CHECK_SKIP_VERIFY true skips the anchors and the audit log chains, on a host without the API's code.

↑↓ to move, Enter to open