.github/workflows/supabase-backup-export.yaml)
is the safety net for moving data off Supabase. It reads a project and writes
age-encrypted files to an R2 bucket that has a bucket lock. Every statement it
sends to Supabase is a read. Agents never run SQL against a Supabase project
themselves; catalog reads and exports run only through this reviewed job.
Modes
Every file except
manifest.json is encrypted to the age public keys in
BACKUP_AGE_RECIPIENTS. At least two keys are required: the owner’s and an
escrowed second holder’s. Losing one key therefore cannot strand a backup.
CI never holds a private key.
The prefix is supabase/<target>/<UTC timestamp>-<run id>-<attempt>/. The
manifest lists each file’s sha256, the git SHA, the run and the parity results.
It is uploaded last, so a partial upload can be recognised.
The manifest is not encrypted, so the hashes can be checked before
decryption. It carries only totals (tables, rows, objects) and no names, and
it sits in the locked, private backup bucket.
Consistency and verification
- One
REPEATABLE READ, READ ONLYtransaction exports a snapshot. The row counts, the storage totals andpg_dump --snapshotall read that snapshot, so the counts describe exactly the data in the dump. - The dump is restored into a local Postgres 17 cluster (PGDG packages, with
pgvector), reachable only through a Unix socket. The restore uses
--no-owner --no-acl.- Supabase-only extensions (pg_cron, pg_net, pgsodium, pg_graphql, wrappers) do not exist there, so objects that depend on them fail. Their errors are counted, not fatal.
- Parity is judged on row counts. Every source table must exist after the restore with the same count.
- Tables owned by an extension (for example
extensions.wrappers_fdw_stats) are left out, becausepg_dumpdoes not dump their data.
- Every bucket listed in
storage.bucketsat the snapshot is copied through Supabase’s S3 endpoint, and parity is checked key by key:- every object with a recorded size must arrive with exactly that size;
- a downloaded file that is not one of those keys is allowed only if the
snapshot listed it as excluded (an unfinished upload with no size, or a key
ending in
/); - a sync error, for example an excluded row with no backend object, is recorded in the encrypted bundle, and the key comparison decides the outcome;
- an upload between the snapshot and the copy fails the run. Re-run it;
- a bucket whose id is not a safe directory name, or that holds a key with a
leading
/or an empty,.or..segment, is not synced, so nothing can be written outside its directory. Storage parity then fails, and the unsafe keys are listed in the encrypted report.
- The archive is streamed straight into
age, so no plaintext tar is written. - Counts run with
row_security = off, so a count fails, aspg_dumpdoes, instead of returning a number silently filtered by RLS. - The restore cluster’s bootstrap superuser is
restore_admin, so replayingroles.sql(which alters the role namedpostgres) never changes the restore’s own admin. - Disk. After the snapshot reads, the job sizes the export from the data:
twice the relation bytes (the dump and the restored cluster), plus twice the
storage bytes (the tree and its archive), plus a 2 GiB margin. It fails early
if the scratch disk (
/mnt) has less. The job timeout is 240 minutes. - A run that uploads files but fails parity exits non-zero. It is not a verified backup.
What the backup leaves out
These schemas are excluded:graphql,graphql_public,net,pgbouncer,pgsodium,pgsodium_masks,realtime,_realtime,supabase_functions,vault,cron,_analytics.
cron.jobrows: the pg_cron schedules;- Vault secrets;
supabase_functionswebhooks.
auth, storage, public, private, extensions and supabase_migrations are
included. The role dump uses --no-role-passwords, so roles are restored
without passwords.
Transport security
- Connections use
sslmode=verify-fullagainst Supabase’s database CA certificate, which is stored in the environment variableSUPABASE_DB_CA_CERT. - The password travels only in
PGPASSWORD, never in a command line.
Public-repository logging
This repository is public, so workflow logs are public too.- The job uploads no artifacts.
- It prints only “Snapshot read.”, pass or fail, the R2 prefix and the manifest’s sha256.
- Parse errors name a line number, never a table, bucket, key or count. A report that cannot be parsed is recorded as a failed parity result, so the archives and the manifest are still uploaded.
- Output from psql,
pg_dump,pg_restoreand the storage copy goes to files. On failure those files are encrypted and uploaded, and the log shows only a generic error. Such output can contain business metrics, object keys or row values: a failedCOPYcan echo a row.
Environment setup
Two environments,supabase-backup-staging and supabase-backup-production,
must be restricted to main and have required reviewers. Create both before
the first dispatch. If a job names an environment that does not exist, GitHub
creates it on first use with no reviewers and no branch policy. A dispatch
before setup still fails closed, because the R2 and pooler secrets are missing.
The project ref and database password come from the repository-level secrets
shared with the migration workflows, chosen by target:
STAGING_PROJECT_ID/STAGING_DB_PASSWORD or
PRODUCTION_PROJECT_ID/PRODUCTION_DB_PASSWORD. This job resolves them only
after its environment gate. Because they are repository-level secrets, any
workflow with write access can still read them, exactly as the migration
workflows do. The script pins each target to its project ref, and a mismatched
password fails authentication.
Each environment holds:
The bucket lock. The backup bucket’s lock rule keeps every object for 90
days, so the job’s token cannot delete or overwrite an export. An account
administrator can still remove the lock rule itself, so R2 admin rights belong
only with the release authority. Backups that contain erased accounts persist for
up to 90 days. That is the documented backup exception to account erasure.
Running it
- Dispatch Supabase Backup Export from
mainwithtargetandmode. Run staging before production. - Approve the environment deployment.
- Record the R2 prefix and the manifest’s sha256 from the job summary.
- To restore, download the prefix, check every file against the manifest, then
decrypt it with
age -d -i <key>. Only key holders can do this.
scripts/backup/backup-manifest.test.mjs cover:
- count parsing, including quoted names;
- parse errors that never echo values;
- failed reports for unparseable input;
- key-level storage parity (missing, resized, unexpected and excluded keys);
- disk sizing;
- manifest hashing.
scripts/backup/storage-parity.mjs, with tests
in storage-parity.test.mjs.