SafeGrd / Supabase backup

How to back up a Supabase database, and get the copy out of the project

A Supabase project is PostgreSQL, so pg_dump works against it. Four things trip up the first attempt: the direct host is IPv6 only, the project holds schemas you did not create, a project cannot take a plain restore, and Supabase's own backups are tied to the project they protect. This page covers each, the two ways to take the dump, where to restore it, and how to check it. The last section is how SafeGrd runs the same steps on a schedule with no server of your own.

What Supabase's backups do, and what they leave out

From Supabase's own documentation, read on 8 October 2026:

PlanDaily backupsPoint-in-time recovery
FreeNone. Supabase recommends exporting with the CLI's db dump.Not offered
ProThe last 7 daysAn add-on, with a Small compute add-on or larger: 7, 14 or 28 days of history
TeamThe last 14 daysThe same add-on
EnterpriseUp to 30 daysThe same add-on

A dump you take yourself, kept in a bucket outside Supabase, is the copy that survives the project. Supabase says as much for Free projects, and it is as true for Pro.

1. The connection string

In the dashboard, Connect shows three strings. Use the session pooler one for a backup:

postgresql://postgres.PROJECT_REF:PASSWORD@aws-0-REGION.pooler.supabase.com:5432/postgres?sslmode=require

2. pg_dump by hand

pg_dump --format=custom --no-owner --no-privileges --file=supabase.dump "$DATABASE_URL"

pg_dump has to be at least as new as the project's PostgreSQL major version (SELECT version() in the SQL editor tells you; 15 and 17 are common). An older one refuses with server version mismatch.

The dump holds every schema the postgres role can read: your tables in public, and Supabase's auth, storage, realtime, extensions, vault and the rest. auth.users is your users, and storage.objects is the list of files in Storage, so you want both. But a new project already has those schemas, with Supabase's own objects in them, which is why the restore in step 5 is not a plain pg_restore into a project.

--no-owner --no-privileges leaves out the OWNER TO and GRANT lines, which name roles such as supabase_admin and authenticated that a local PostgreSQL does not have. Restoring elsewhere is far easier without them; a restore into a project has the roles anyway.

3. The Supabase CLI

supabase db dump runs pg_dump in a container with the right version and skips Supabase's own schemas, so what it writes loads into a new project. Supabase's migration guide takes three dumps:

supabase db dump --db-url "$DATABASE_URL" -f roles.sql --role-only
supabase db dump --db-url "$DATABASE_URL" -f schema.sql
supabase db dump --db-url "$DATABASE_URL" -f data.sql --use-copy --data-only

The dumps leave out auth, storage and the schemas extensions make. That is what you want for moving to a new project, and what you do not want for a backup: triggers and policies you added to auth or storage are not in it, and neither are the rows. Take the CLI's dumps for a migration, and the plain pg_dump above, or SafeGrd, for a backup.

4. Schedule it somewhere that is not the project

A Supabase project has no server you can put a cron job on. A scheduled GitHub Actions workflow is the usual host: it runs on GitHub's runners, reaches the pooler over IPv4, and needs only two repository secrets. Encrypt before upload, so the runner's log and the bucket hold ciphertext only:

on:
  schedule: [{cron: "15 2 * * *"}]
jobs:
  backup:
    runs-on: ubuntu-latest
    steps:
      - run: sudo apt-get install -y postgresql-client-17 age
      - run: set -o pipefail; pg_dump -Fc --no-owner --no-privileges "$DATABASE_URL" | age -r "$AGE_RECIPIENT" | aws s3 cp - "s3://$BUCKET/supabase/$(date -u +%F).dump.age"
        env:
          DATABASE_URL: ${{ secrets.DATABASE_URL }}

set -o pipefail is the line that matters: without it a pg_dump that dies halfway still uploads the truncated stream and the job is green. Add the AWS credentials as secrets or an OIDC role, and a bucket with Object Lock so the file cannot be deleted before its date (how). Then put a check on the bucket that alerts when a day's file does not arrive, because a disabled workflow fails nothing.

Dumps read the whole database every night. Supabase meters egress after the plan's allowance (5 GB on Free, 250 GB on Pro), so a 10 GB database dumped nightly is about 300 GB a month; safegrd estimate prints the figure for your database (estimate).

A scheduled GitHub Actions runner connects to your Supabase project through the session pooler over IPv4, since the direct host is IPv6 only. It pipes pg_dump through age and uploads the encrypted dump to your bucket outside Supabase, under Object Lock. Daily backups and PITR stay inside the project and are deleted with it. your Supabase project Postgres direct host: IPv6 only session pooler IPv4, port 5432 Supabase's backups go with the project GitHub Actions cron, 02:15 UTC pg_dump | age | s3 cp your bucket outside Supabase, Object Lock
The runner reaches the project through the session pooler and writes an encrypted dump to a bucket outside the project. Deleting the project removes Supabase's backups. The copy in your bucket cannot be deleted before its lock date.

5. Restore

On your machine, to check it or to read it

A plain postgres image lacks Supabase's extensions (supabase_vault, pg_graphql), and the dump's CREATE EXTENSION lines fail there. Supabase's own image has them, with supabase_admin as superuser:

docker run -d --name restore -e POSTGRES_PASSWORD=restore -p 54320:5432 supabase/postgres:17.6.1.178
psql "postgres://supabase_admin:restore@localhost:54320/postgres" -c "CREATE DATABASE restored"
pg_restore --exit-on-error --no-owner --no-privileges --dbname "postgres://supabase_admin:restore@localhost:54320/restored" supabase.dump

Pick the image tag that matches the project's version, from the PG: prefix in the dashboard's backup list or SELECT version(). A dump from the dashboard's own backup download is a different file: Supabase's guide restores that one with supabase db start --from-backup.

Into a project, after an incident

A project is never empty, and postgres there is not a superuser, so a full pg_restore fails on the first object Supabase already owns. Restore the schemas that are yours and load rows into the ones that are Supabase's:

pg_restore --exit-on-error --single-transaction --schema=public --dbname "$DATABASE_URL" supabase.dump
pg_restore --schema=auth --schema=storage --data-only --file=auth-storage.sql supabase.dump
psql -v ON_ERROR_STOP=1 --single-transaction -c "SET session_replication_role = replica" -f auth-storage.sql "$DATABASE_URL"

--single-transaction rolls everything back on the first error, so a half-loaded project is not a state you can end up in. This path is tested against PostgreSQL, not yet against a Supabase project.

6. What a database dump does not hold

Row-level security and the role

The project's postgres role owns the tables you make in the dashboard and bypasses row-level security, so a dump as postgres holds every row. A separate read-only role (GRANT pg_read_all_data) does not bypass RLS. Its dump stops at the first table with policies, with query would be affected by row-level security policy and exit code 1. Adding --enable-row-security gets past the error by dumping only the rows the policies show the role, often none, with exit code 0. Give the role BYPASSRLS instead, and check the dump's row counts against the project's (the errors, reproduced; the role, on Databases).

What PITR costs, and what a copy outside the project costs

From Supabase's pricing page and its PITR and compute guides, read on 18 October 2026. PITR is an add-on to a paid plan (Pro from $25 a month), priced by the hour:

PITR historySupabase's price
7 days$0.137 an hour, about $100 a month
14 days$0.274 an hour, about $200 a month
28 days$0.55 an hour, about $400 a month

SafeGrd is priced per organization, not per project: one plan covers every database, from $15 a month, with a free tier. The two do different jobs. PITR rewinds the project to a second inside its window. A SafeGrd backup restores the moment it was taken, from a bucket outside Supabase, on any machine, after the project is gone, and SafeGrd restores the backups on a schedule to prove they work:

Each backup reads the whole database, which counts against Supabase's egress: 250 GB a month are included on Pro and Team, then $0.09 a GB. A 10 GB database backed up nightly reads about 300 GB a month, about $4.50 over the allowance. safegrd estimate prints the figure for yours.

How SafeGrd does it

SafeGrd runs the steps above on a schedule and keeps the record. From a scheduled GitHub Actions job, it dumps the project through the session pooler, with auth and storage included, encrypts on the runner, and writes to storage that refuses deletes until the lock ends. Each backup uploads only what changed since the last one; the read is still the whole database, so Supabase's egress is about the database's size per backup, which safegrd estimate prints. On a schedule SafeGrd restores it on a machine started for that drill and destroyed when it ends, into Supabase's own PostgreSQL image, and checks every table's row count against the manifest written at backup time.

Or let SafeGrd take the backup itself, with no workflow to keep: Back up on SafeGrd under Surfaces in the console signs you in to Supabase, lists your projects with the pooler address filled in, and takes the project's database password. A machine SafeGrd starts for each backup dumps and encrypts it, then is destroyed. The connection string is sealed and given only to that machine (how).

Run your first Fire Drill Read the setup guide

- uses: safegrd/backup-action@v0
  with:
    config: ${{ secrets.SAFEGRD_CONFIG }}
    database-url: ${{ secrets.DATABASE_URL }}

A restore is one command, on any machine with the CLI: the whole database into Supabase's image, or --schema public --data-only-schema auth --data-only-schema storage into a project, in one transaction that rolls back if a row count does not match (the restore steps).

Questions

Do I need a server?

No. Either SafeGrd backs it up (Back up on SafeGrd in the console, with the connection string), or the GitHub Action is the host: it needs a SafeGrd config in a repository secret and the database URL in another. Storage can be your own S3-compatible bucket or SafeGrd's hosted storage, which is locked in compliance mode.

Who holds the decryption key?

With a SafeGrd-managed key, SafeGrd keeps your key sealed and releases it only to your enrolled hosts, so you can restore even after losing a host, and the workflow needs no key of its own. With a customer-managed key, only you can decrypt these backups, and the drill job takes the key from a secret.

Is this a replacement for Supabase's PITR?

No. PITR restores the project to any second in its window; a dump restores to the moment it was taken. Teams that need both run PITR for the quick undo and keep a nightly dump outside the project for the case PITR does not cover: the project itself going away.

How is this different from BackupDrill?

BackupDrill connects to Supabase by OAuth and drills in its own cloud. SafeGrd backs up from your workflow into storage under Object Lock, and drills other databases, files and mail the same way (SafeGrd vs BackupDrill).

Related