Restoring on a bad day
Something went wrong, and you need yesterday’s data. Take a breath: if your drills have been passing, this works. Do it from your laptop, in the folder whose .env has the private key.
-
Find the backup.
Terminal window pgb list2026-11-16T020000Z 48.1 MB shop/2026-11-16T020000Z.dump.age2026-11-17T020000Z 48.2 MB shop/2026-11-17T020000Z.dump.age2026-11-18T020000Z 48.2 MB shop/2026-11-18T020000Z.dump.ageLast drill: PASS, 12 days agoStamps are UTC. Pick the newest one from before the accident. With TIERS, older backups may only be in
monthly/, so name themmonthly/<stamp>. -
Check it opens, without touching any database:
Terminal window pgb verify 2026-11-17T020000Z -
Restore into a new, empty database, not over the live one. Create it first, then put it in
.env:Terminal window RESTORE_DATABASE_URL=postgresql://user:password@host:5432/shop_restoredTerminal window pgb restore 2026-11-17T020000ZTerminal window docker run --rm -it --env-file .env ghcr.io/iotabyt/pgbackup-r2:pg17 restore 2026-11-17T020000ZIt downloads the backup, checks the checksum, decrypts it, and runs
pg_restore --clean --if-exists. -
Look at the restored data. Check the rows you care about, then switch your app’s
DATABASE_URLover, or copy the rows you need back into the live database.
Why RESTORE_DATABASE_URL, not --target
Section titled “Why RESTORE_DATABASE_URL, not --target”--target URL still works and takes precedence. But anything on a command line, the password included, is visible to every user on the machine who runs ps, and it ends up in your shell history. From .env, the URL only ever lives in environment variables, and pg_restore gets the password through PGPASSWORD.
pgb treats RESTORE_DATABASE_URL the same way as DATABASE_URL. localhost works, and so does a Compose service name with PGB_NETWORK.
Overwriting production
Section titled “Overwriting production”A restore into the same database as DATABASE_URL is refused. To overwrite production deliberately:
pgb restore 2026-11-17T020000Z --to-productionYou’ll then have to type the database name at an interactive terminal to confirm. pgb gives the container a terminal when you run it from one.
A plain dump file instead
Section titled “A plain dump file instead”To restore somewhere the tool can’t reach, or to hand the dump to someone, decrypt it to a normal pg_dump file:
pgb decrypt 2026-11-17T020000Z --out /out/shop.dumpmkdir -p outdocker run --rm -it --env-file .env -v "$PWD/out:/out" --user "$(id -u):$(id -g)" \ ghcr.io/iotabyt/pgbackup-r2:pg17 decrypt 2026-11-17T020000Z --out /out/shop.dumpThe file appears as out/shop.dump. Restore it with:
pg_restore --no-owner --no-acl -d <database> out/shop.dumpA .dump.age you’ve already downloaded works too. Put it in out/ and decrypt it with no S3 settings at all:
pgb decrypt --file /out/2026-11-17T020000Z.dump.age --out /out/shop.dumpIf the manifest (.manifest.age) sits next to it, the checksum is checked as well.
Troubleshooting: fixes for common problems, and every doctor message.
pgbackup-r2 is an open-source tool from Iotabyt. MIT licensed.