How to back up a Supabase project

A green “backup complete” badge is nice to see. It also leaves a lot unanswered. Can the file be restored? Are the Storage files there? How long will the whole job take when production is down? Start with those questions, then work backwards.

A Supabase project is more than Postgres. Storage, Auth settings, Edge Functions, API keys and project configuration all live in different places. One dump cannot contain all of it.

What Supabase’s built-in database backups cover

Supabase documents that paid projects receive automatic daily database backups, while Point-in-Time Recovery provides finer recovery points. Those database backups include database metadata for Storage, but not the actual objects stored through the Storage API. A restored row can therefore exist while the corresponding file is gone.

Project deletion is another boundary. According to the Supabase project deletion documentation, deleting a project permanently removes its database, Storage objects, backups, and configuration. A provider-managed backup inside the same project lifecycle is therefore not an independent copy.

Build the backup around four separate assets

1. PostgreSQL database

Use a logical dump for portable recovery. PostgreSQL’s pg_dump documentation notes that a dump is consistent even while the database is in use and does not block readers or writers. It also makes an important limitation explicit: pg_dump handles one database, not cluster-wide roles and tablespaces.

• Capture schema and data, not just one or the other.
• Record the PostgreSQL and pg_dump versions with the artifact.
• Keep role and ownership requirements explicit; do not assume credentials are recoverable from a database dump.

2. Supabase Auth data

Auth users and identities are stored in Postgres, but auth-provider settings, secrets, redirect URLs, email templates, and API keys are project configuration. Validate user and identity counts after a restore, then keep a separate configuration runbook for the settings that are not rows in the dump.

3. Storage objects

Back up the bytes as well as the storage metadata. For every object, retain its bucket, path, size, and a checksum such as SHA-256. During verification, download the restored object and compare its checksum. Counting rows in storage.objects cannot prove that the underlying files survived.

4. Project configuration and application dependencies

Supabase’s restore-to-a-new-project guide lists items that require separate handling, including Storage objects and settings, Edge Functions, Auth settings and API keys, and Realtime settings. Put those in version control or an encrypted recovery runbook. A database restore cannot recreate a secret it never contained.

Keep an independent copy

Independence means a production administrator mistake, billing problem, compromised account, or provider lifecycle event cannot remove both the source and the backup. Store backup artifacts in a separate account or managed backup service, encrypt them, limit deletion rights, and define retention deliberately.

Do not rely on downloading a backup once and forgetting it. Scheduled copies, immutable retention, observable failures, and periodic restore tests turn a file into a recovery system.

The restore test that makes the backup credible

1. Provision an empty, isolated PostgreSQL target with a compatible major version.
2. Restore the dump with errors treated as fatal. Do not accept a restore that continues after failed statements.
3. Compare schemas, tables, extensions, row counts, Auth users, and Storage inventory against the source snapshot.
4. Run application-level smoke tests: sign in, read a representative record, exercise row-level security, and fetch a restored object.
5. Destroy the temporary target and retain a verification report with duration, versions, and differences.

For custom-format dumps, PostgreSQL supports an all-or-nothing restore through pg_restore --single-transaction. That prevents a half-restored database from being mistaken for success.

A minimum production checklist

• Daily automated database backups, with retention matched to your recovery window.
• An independent copy outside the Supabase project lifecycle.
• Storage object bytes backed up separately and verified by checksum.
• A documented inventory of configuration, secrets, Edge Functions, and provider settings.
• Automated restore verification after every backup, plus an application recovery drill on a schedule.
• Alerts that reach a human when backup or verification fails.

If you would rather not maintain this yourself, see how ReviveDB backup verification works or review the Supabase disaster recovery workflow. Either way, do a real restore before you trust the backup.