supa-backup

Your Supabase backup is worthless if it can't restore.

supa-backup is a Supabase-aware Postgres backup CLI that handles the restore pitfalls naive pg_dump misses — and then proves your backup restores with a built-in verification manifest.

Why this exists

Real failure modes reported by Supabase users:

• Restoring into another instance fails with duplicate keys and must be owner of table secrets (supabase/cli#3532)
• Schema restores fine but data is missing (discussion #34785)
• Custom role passwords silently absent after restore (pg_dump never carries them)
• Native backups are physical snapshots: not portable, 7-day retention on Pro, Storage buckets not included

supa-backup addresses each one:

| Pitfall | What we do | |---|---| | Managed-schema conflicts (vault, auth, schema_migrations) | Excluded at dump time — the platform recreates them, your restore shouldn't fight them | | Silent bad dumps | Verification manifest (row counts, checksums, RLS policy count) written at backup time | | "Does it actually restore?" | supa-backup verify — restore into staging, compare against the manifest, exit 0/1 (CI-friendly) | | Role passwords | Detected and warned about explicitly |

Install

npm install -g @shipquiet/supa-backup
# requires pg_dump/pg_restore/psql >= your server's major version

Usage

# 1. Back up (direct connection string, port 5432 — not the pooler)
supa-backup backup \
  --db "postgres://postgres:[email protected]:5432/postgres" \
  --s3-endpoint https://ACCOUNT.r2.cloudflarestorage.com \
  --s3-bucket my-backups

# 2. Restore into a staging project
supa-backup restore --db "postgres://...staging..." --from backup-2026-08-15.dump

# 3. Prove it worked
supa-backup verify --db "postgres://...staging..." --manifest backup-2026-08-15.manifest.json

Want this automated?

restoproof (hosted) runs your backups on schedule, ships them to your S3/R2, and runs a weekly restore drill in an isolated Postgres — emailing you a "restore verified" report, or an alert the moment a backup stops being restorable. From $9/mo.

License

MIT