backupdrill: the free, open-source Supabase backup CLI
An open-source (MIT) CLI that backs up a Supabase project to your own S3, R2, or B2 bucket: the Postgres database and, once you add the project’s Storage S3 keys, your Storage files. Each backup includes a checksummed manifest.json that records what was saved. Backups stream from your machine or CI straight to your bucket and never pass through our servers. Source and issues at github.com/backupdrill/cli.
Requirements
Node.js ≥ 20, and a pg_dump whose major version is ≥ your Supabase Postgres version (Supabase runs PG 15–17). On macOS: brew install libpq and add it to PATH, or point BACKUPDRILL_PG_DUMP at the binary. The CLI checks this and refuses to run a mismatched dump.
Install
npm install -g backupdrill
# or run without installing:
npx backupdrill backupConfigure
Set options with environment variables, a config file, or flags. Flags win over environment variables, which win over the file. Use the Session pooler connection string from the Connect button at the top of the Supabase dashboard; the postgres user in it works as-is. A read-only backup_reader role is an advanced option that only works if your schema has no RLS-enabled tables. See the advanced setup in the quickstart.
export BACKUPDRILL_DATABASE_URL="postgresql://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com:5432/postgres"
export BACKUPDRILL_PROJECT_NAME="my-app"
export BACKUPDRILL_S3_ENDPOINT="https://<account>.r2.cloudflarestorage.com" # omit for AWS S3
export BACKUPDRILL_S3_REGION="auto"
export BACKUPDRILL_S3_BUCKET="my-backups"
export BACKUPDRILL_S3_ACCESS_KEY_ID="…"
export BACKUPDRILL_S3_SECRET_ACCESS_KEY="…"The database dump covers the public schema by default and doesn’t include Storage files. Supabase’s own database backups have the same gap: they keep the storage.objects metadata, not the files. To back up the files, enable S3 access under Storage → Settings → S3 Access Keys in the Supabase dashboard and add:
export BACKUPDRILL_SUPABASE_STORAGE_ENDPOINT="https://<ref>.storage.supabase.co/storage/v1/s3"
export BACKUPDRILL_SUPABASE_STORAGE_REGION="<project-region>"
export BACKUPDRILL_SUPABASE_STORAGE_ACCESS_KEY_ID="…"
export BACKUPDRILL_SUPABASE_STORAGE_SECRET_ACCESS_KEY="…"
# optional: only specific buckets
export BACKUPDRILL_SUPABASE_STORAGE_BUCKETS="avatars,uploads"Since 2.10.0 the CLI also saves your Supabase Auth users (auth.users and auth.identities: emails, password hashes, sign-in methods) as auth.dump next to the database dump, whenever the role in your connection string can read them. To leave them out, set BACKUPDRILL_AUTH=off or pass --no-auth. restore writes them in the same transaction as the database; --skip-auth restores the database without them.
Commands
backupdrill backup # dump DB and Auth users (+ Storage files if configured) to your bucket
backupdrill estimate --plan pro # project your monthly Supabase egress cost before scheduling
backupdrill drill # restore latest snapshot into a throwaway Postgres (needs
# Docker) and verify it; --snapshot <timestamp> to pick one,
# --verify-all-files to checksum every Storage file
backupdrill drill \
--check-cmd "npm run smoke" # v0.2: after structural checks pass, run YOUR smoke test
# against the restored copy (BACKUPDRILL_SANDBOX_URL is set;
# exit 0 = pass, reported as 'app checks'); --keep holds the
# sandbox open on failure for inspection
backupdrill restore --database \
--storage-dir ./recovered \
--dry-run # real recovery into a fresh project: DB connection string
# from BACKUPDRILL_TARGET_DATABASE_URL (or a hidden prompt),
# files to a local folder; check with --dry-run, then rerun
# with --confirm-target <ref> in place of --dry-run to write
backupdrill drill --record # also leave the drill's outcome in the bucket (2.6.0+)
backupdrill exporter # Prometheus metrics on 127.0.0.1:10059/metrics (2.6.0+)For the full recovery steps, including a raw pg_restore fallback, see Restore & recovery.
To get alerts in Prometheus when backups stop or a drill fails, see Monitor Supabase backups with Prometheus.
Egress cost: read before scheduling daily backups
A backup pulls data out of Supabase, which is uncached egress on your Supabase bill: $0.09/GB above your plan’s allowance (Free 5 GB, Pro/Team 250 GB per month). Spend Cap exists only on Pro, where it’s on by default. Go over the quota with it on and Supabase emails your billing address and normally gives you a grace period (not if you used one up in a recent billing cycle). After that it can restrict egress, your app’s included, until the next billing cycle or until you turn Spend Cap off, and backups fail while that lasts. Team has no Spend Cap, so egress past the quota goes on the bill. Free is a hard cap: a large daily backup can’t complete on it. Rough cost on Pro with Spend Cap off, or on Team, with backups as your only egress:
| DB + Storage | Weekly | Daily |
|---|---|---|
| 10 GB | $0/month (within 250 GB) | ~$4.50/month |
| 50 GB | ~$0/month | ~$112/month |
Cost scales with size × frequency. Run backupdrill estimate for your own numbers, and prefer weekly once your data is large.
Schedule it with GitHub Actions
The repo includes a workflow template at examples/scheduled-backup.yml. Copy it into your own repo as .github/workflows/scheduled-backup.yml. It runs daily (or on demand from the Actions tab) and installs a matching pg_dump for you. Add these repo secrets: BACKUPDRILL_DATABASE_URL, BACKUPDRILL_S3_BUCKET, BACKUPDRILL_S3_ACCESS_KEY_ID, and BACKUPDRILL_S3_SECRET_ACCESS_KEY; the endpoint, region, project name, and Storage-file variables are optional. Read the egress section above before going daily.
To hear about a run that fails or never starts, add a BACKUPDRILL_PING_URL secret with a Healthchecks.io check’s ping URL (CLI 2.5.0 and newer): Monitor Supabase backups with Healthchecks.io.
Backing up a Postgres database that is not on Supabase? The pg_dump to S3 guide has a plain shell script and schedule for any host.
The hosted service runs the same engine and adds scheduling, restore drills, failure alerts, and reports, so you don’t have to remember to run anything. The quickstart walks through setup.
Start free