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:
| Plan | Daily backups | Point-in-time recovery |
|---|---|---|
| Free | None. Supabase recommends exporting with the CLI's db dump. | Not offered |
| Pro | The last 7 days | An add-on, with a Small compute add-on or larger: 7, 14 or 28 days of history |
| Team | The last 14 days | The same add-on |
| Enterprise | Up to 30 days | The same add-on |
- They are deleted with the project. "When you delete a project, we permanently remove all associated data, including any backups stored in S3." A project deleted by mistake, by a script, or by someone with the dashboard login takes its backups with it.
- Turning on PITR turns off daily backups. The history window replaces them, and physical backups are not available for download. For a file you can keep, take a logical dump.
- Daily backups do not carry custom role passwords, and they restore into the same project. They undo a bad day inside the project.
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:
- Not the direct host.
db.PROJECT_REF.supabase.co:5432has an IPv6 address only, unless you pay for the IPv4 add-on. GitHub's runners, most CI, and many home connections have no IPv6, and the error is a plain timeout. - Not the transaction pooler. Port 6543 shares one server connection
between clients and hands it over between transactions.
pg_dumpneeds one connection for the whole run to read every table from one snapshot, and it fails partway through with a prepared-statement or snapshot error. - Port 5432 on the pooler host gives each client its own server
connection, over IPv4, on every plan. The user is
postgres.PROJECT_REF, notpostgres. sslmode=require, so the driver refuses to connect without encryption. Most drivers default toprefer, which falls back to plaintext.
2. pg_dump by hand
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:
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:
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).
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:
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 --schema=publicrecreates your tables and their rows. Drop or rename the project'spublictables first, since the restore creates them.- The rows of
authandstoragego back into the tables the project already has, with triggers off for the load, as Supabase's migration guide does it:SET session_replication_role = replicafirst, so encrypted columns are not encrypted twice.pg_restorecannot set that, so write those rows out as SQL and load them withpsql.
--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
- The files in Storage.
storage.objectsis their list; the bytes are in Supabase's object store. Copy them with the Storage API or an S3-compatible client against the project's S3 endpoint, on the same schedule. SafeGrd does this from the same sign-in as the database, every bucket, with no key typed (how). - Vault's root key. Secrets in
vaultare encrypted with a key the dump cannot read. A new project gets a new key, so the old secrets do not decrypt there. Supabase's guide says to copy the key before pausing or deleting the old project. - Role passwords, when the dump runs as anything but a superuser. Set them again after a restore.
- Edge Functions, Realtime publications, webhooks and project settings. Keep the functions in git. Re-enable the rest in the dashboard.
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 history | Supabase'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 |
- It needs a Small compute add-on or larger. Small is about $15 a month, against about $10 for Micro.
- It replaces daily backups. "If you enable PITR, we will no longer take Daily Backups."
- It is per project. Three projects with 7 days each are about $300 a month, before compute.
- It is deleted with the project, like the daily backups above.
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:
- Free: weekly, checked in memory
- Starter, $15 a month: weekly, loaded into a throwaway database
- Growth, $49 a month: daily, loaded into a throwaway database
- Scale, $149 a month: daily, loaded into a throwaway database
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
- How to back up Supabase with GitHub Actions: the SafeGrd workflow, step by step
- Supabase backup tools compared: eleven options, which keep the Storage files and which test the restore
- How to back up a PostgreSQL database: pg_dump's formats and flags, restore and the check
- Object Lock cost calculator: what a retention plan stores