Guides

Backups and restore

Make a local logical backup, optionally copy it to S3, and restore it without replacing the live staging database.

Make a backup

Keep the instance running with stage-pg run while you back it up or restore it.

stage-pg backup ./stage-data

The command uses the stage_admin role and pg_dump --format=custom. A successful backup creates a set like this:

stage-data/backups/
  20260807T180000Z.dump
  20260807T180000Z.json
  20260807T180000Z.sha256

The dump is published only after:

  1. pg_dump exits successfully;
  2. the dump is non-empty;
  3. pg_restore --list can read it;
  4. the checksum and manifest are written.

The files are written through temporary .part files, so an interrupted backup does not look complete.

Keep local backups

backup.keepLocal controls how many complete local backup sets remain. The newest successful set is always protected from pruning.

Local retention is not host backup. A disk failure, deleted instance folder, or lost machine can still destroy every local copy.

Upload to S3-compatible storage

Add an s3 block to config.json as shown in Configuration, then export AWS-style credentials:

export AWS_ACCESS_KEY_ID='…'
export AWS_SECRET_ACCESS_KEY='…'
stage-pg backup ./stage-data

The uploader writes the dump, checksum, and manifest under a date-based key such as:

stage-pg/2026/08/07/20260807T180000Z.dump

The CLI does not delete remote objects. Use the bucket's lifecycle policy for remote retention.

Warning

The local dump is not application-encrypted by stage-pg. Protect the backup directory, the bucket, and the credentials that can read or write it.

If the S3 upload fails, the command reports an error but keeps the verified local files. The upload status is recorded in state.json and the manifest.

Restore into a new database

Pass a dump or manifest filename:

stage-pg restore ./stage-data 20260807T180000Z.dump

The command checks:

  • the manifest format;
  • the dump size;
  • the SHA-256 checksum;
  • the PostgreSQL major version;
  • whether the administrator role can create a database.

It then creates a new database with a name like staging_restore_20260807_180000, restores the dump, and checks the database owner.

The original staging database is not replaced. There is no destructive restore option in v1.

What a logical backup does not include

These backups do not provide:

  • point-in-time recovery;
  • WAL archiving;
  • high availability;
  • a full copy of the host;
  • automatic backup of every cluster-wide object.