DEV Community: AK D

What a Supabase database backup leaves out

AK D — Thu, 15 Oct 2026 08:12:27 +0000

A Supabase database backup restores your Postgres data. Most projects depend on more than that, and the gaps only show up when you restore into a new project.

Here is what does not come back from the database backup alone.

What	Where it lives	In the database backup?
Tables, rows, RLS policies, functions	Postgres	Yes
Auth users	`auth` schema in Postgres	Yes, if you back up that schema
Storage file contents	Object storage	No, only the metadata rows
Edge Function code	Deployed separately	No
Edge Function secrets	Project settings	No
Passwords of custom database roles	Postgres roles	Need to be reset after a restore

Storage files

The storage.objects table tells you which files exist. The files themselves are not in it. After a restore the app can list every file and download none of them. You need a separate copy of the bytes, ideally from the same moment as the database backup.

Auth users with pg_dump

A common pg_dump example uses --schema=public to skip the Supabase-managed schemas. That also skips auth, so the restored project has your data but no user accounts. If you dump manually, include auth or dump the full database.

Edge Functions

Function code is deployed from your machine or CI, not stored in Postgres. If the code lives in Git, you can redeploy it. If someone deployed from a laptop and never committed, the database backup will not help. Secrets have to be set again by hand.

Test it once

The only way to know what your backup covers is to restore it into an empty project and use the app. Log in, open a page with images, call a function. Whatever breaks is what your backup is missing.

I wrote a longer comparison of the Supabase backup options and what each one covers. If you'd rather not script all of this yourself, ReviveDB backs up the database, Auth, Storage files and Edge Functions together and test-restores every database backup.

How to test the database layer of a Supabase backup

AK D — Thu, 01 Oct 2026 13:00:00 +0000

To test a Supabase database backup, restore it into a clean, isolated target with errors treated as fatal. Compare schemas, roles, row counts and sequences with an inventory captured at backup time, then run application checks. Record the restore result and duration for each test.

Why a valid dump can still fail you

A dump may be readable and still be operationally useless. Missing roles can break ownership. Absent extensions can stop schema creation. A version mismatch can surface incompatible syntax. A restore may log errors, continue, and leave behind a database that looks populated but is incomplete.

PostgreSQL documents that pg_dump creates a consistent snapshot without blocking readers or writers. It also documents the boundary: pg_dump exports one database and does not include cluster-wide roles and tablespaces. A restore plan must account for everything outside that boundary.

1. Capture a source inventory

Before restoring, record what “complete” means. At minimum, capture the server version, extensions, schemas, tables, sequences, views, functions, row counts, and ownership expectations. For products built on Postgres, add domain checks such as user counts, tenant counts, or object inventory.

Take the inventory at the same logical point as the backup. Comparing a restored nightly dump with a live database the next afternoon produces noise, not evidence. Store the source inventory beside the backup artifact and identify both with the same run ID.

2. Restore into a clean, isolated target

A clean target exposes hidden dependencies. Restoring repeatedly into a long-lived test database can succeed only because an extension, role, or table survived a previous run. Provision a disposable database for each verification and remove it afterward.

Match the production PostgreSQL major version unless you are deliberately testing an upgrade.
Block application traffic and outbound integrations from the verification environment.
Use temporary credentials and never send production emails, webhooks, or jobs.

3. Make restore errors fatal

For a custom-format archive, use pg_restore with an error policy that cannot silently leave a partial result. PostgreSQL’s --single-transaction option executes the restore as one transaction and implies exit-on-error: either all commands complete or none are applied.

If the database is too large for one transaction, fail on the first SQL error, keep the logs and throw the target away after a failure. The exact flag matters less than refusing to call a partial restore successful.

4. Compare structure and data

Start with inventory because it catches broad omissions quickly. Compare schemas, relations, extensions, and row counts. Then add checks that represent business value. A table count cannot tell you whether the latest subscription exists or whether a restored user can access the correct tenant.

Schema objects: names and types, with expected exclusions documented.
Data: row counts plus targeted invariants and representative records.
Security: roles, ownership, grants, and row-level-security policies.
Sequences: next values must not collide with restored rows.
Large objects and external files: count, size, and checksum where applicable.

5. Run application-level recovery checks

Database equivalence is necessary but not sufficient. Point a safely isolated application build at the restored target and exercise a short recovery script: authenticate, read a core record, perform a transaction, verify permissions, and retrieve a file if the product uses object storage.

Keep the smoke test small and deterministic. Its purpose is to catch broken contracts between the application and the restored state, not to replace the full test suite.

6. Measure and retain evidence

Record artifact identity and checksum, source and target versions, start and finish times, restore logs, inventory differences, smoke-test results, and the final disposition. This turns “we tested it once” into evidence that can be reviewed after a change or incident.

Track restore duration over time. A backup that restores correctly in six hours still fails a two-hour RTO. Growth in recovery time is an operational signal, just like growth in database size.

Check the target version after a PostgreSQL upgrade

Supabase’s PostgreSQL 15.19 and 17.11 release notice lists four conditional changes: two for ltree indexes, one for btree_gist indexes on floating-point columns and one for legacy pgcrypto ciphers. It also limits how custom operators with a selectivity estimator can be recreated. Run its detection queries for the project before upgrading; a passing row-count comparison alone does not rule them out.

Custom operators with a non-built-in selectivity estimator can fail to recreate during a logical restore on the new minor version because Supabase roles are not superusers. Treat that SQL error as a failed restore. Use the official detection query and remove the estimator or contact Supabase support before relying on the dump.
Existing ltree indexes and btree_gist indexes on floating-point values containing NaN may return incomplete or wrong results after the upgrade. Use Supabase’s conditions and index queries to identify affected indexes, then reindex them on the upgraded source. A fresh scratch restore builds new indexes and cannot prove that old source indexes were rebuilt.
If the application used legacy pgcrypto PGP ciphers such as blowfish or cast5, test decryption on the target version with a controlled sample. A successful restore and matching row counts do not prove that the values can still be decrypted. Follow Supabase’s migration instructions for affected ciphertext.

Run the next restore drill against the PostgreSQL minor version planned for recovery and keep its log. Separately verify application queries against the upgraded source, because the restored target and the existing source can fail in different ways.

How often should you test?

Automate a structural restore test for every backup when the database size and cost make that practical. Run deeper application recovery drills on a slower schedule and after meaningful changes to versions, extensions, backup tooling, or infrastructure. The test frequency should follow the rate at which your recovery assumptions can change.

A result you can trust

Use three outcomes: verified, failed, or verified with explicitly accepted differences. Never turn unexplained differences into success just to keep the dashboard green. Expected exclusions should be versioned policy; everything else deserves investigation.

I build ReviveDB, which runs this restore-and-compare check on every Supabase database backup. This post was first published on the ReviveDB blog.

Do Supabase backups include Storage files?

AK D — Mon, 28 Sep 2026 08:50:56 +0000

No. Supabase database backups do not include the actual files in Supabase Storage. They keep the rows that describe those files. That is easy to miss: after a database restore the catalogue can look fine while every download returns an error.

What survives a Supabase database restore?

Storage component	In the database backup?	Separate recovery required?
Bucket and object metadata rows	Yes	Verify that metadata matches the selected recovery point
Actual file bytes	No	Yes. Copy and restore every object separately
Public/private bucket setting	Not reliably portable as database-only recovery	Capture and recreate through the Storage API
File-size and MIME-type restrictions	No	Capture and recreate through the Storage API
Object checksum evidence	No	Create a manifest while copying the bytes

The practical test is simple: after recovery, can the application download the expected bytes? A restored storage.objects row proves only that the catalogue entry exists.

Supabase states this directly in its database backups documentation: database backups include Storage metadata but not objects stored through the Storage API. To restore both, keep the PostgreSQL data and object bytes from the same backup window.

Metadata and files are two different assets

Supabase Storage uses database records to describe buckets and objects. Those records contain information such as the bucket, object path and ownership. The content of a PDF, image or video is stored separately. Restoring only the database can recreate the catalogue without recreating what the catalogue points to.

A row count is consequently not a file-integrity check. Ten thousand restored object rows can coexist with zero recoverable files. Verification must fetch the bytes and compare them with evidence captured when the backup was made.

What a useful Storage backup records

The bucket and full object path, preserving case and special characters.
The object size and content type.
A cryptographic checksum, such as SHA-256, calculated from the downloaded bytes.
The backup timestamp and the database snapshot it belongs to.
Any version or generation identifier used by the destination object store.

The timestamp relationship matters. If database metadata is captured at 02:00 but file copying continues until 05:00, files may be created, replaced or deleted between those moments. Your recovery report should expose that consistency window instead of presenting both artifacts as one perfectly synchronized snapshot.

Ways to copy Supabase Storage objects

Supabase documents several download paths, including its client libraries, the CLI and the S3-compatible endpoint. The official object download guide is the best starting point because the appropriate method depends on volume and automation requirements.

Small projects

For a small inventory, list objects, download each object and write a manifest containing size and checksum. Retry individual failures, but make the final job fail if any object remains missing. A partially successful copy should never receive a green status.

Larger projects

Use bounded concurrency, resumable transfers where available and an object store in a separate account or provider. Keep deletion rights separate from normal application credentials. A backup that can be deleted by the same compromised credential as production is not an independent recovery layer.

How to test a Storage restore

Restore the matching database backup into an isolated Supabase or PostgreSQL recovery environment.
Recreate the required buckets and access policies through a documented process.
Upload the backed-up objects to the paths referenced by the restored metadata.
Compare expected and restored object counts, sizes and checksums.
Use the application to download representative private and public objects.

Include edge cases in the sample: a large object, a path containing spaces, a private object, an object owned by a user and a recently replaced file. These checks catch problems that a single public image cannot.

What happens when a Supabase project is deleted?

Supabase describes project deletion as irreversible and says it removes the database, Storage objects, backups, functions and configuration. See the project deletion documentation. If accidental or malicious project deletion is within your threat model, copies must live outside that project lifecycle.

The practical answer

Treat the Postgres dump, Storage-object copy and configuration inventory as separate artifacts joined by one recovery run. Back up each one, retain them independently and prove they work together. That is the difference between restoring a list of filenames and restoring a working product.

Supabase Storage backup questions

Does PITR back up Supabase Storage objects?

No. PITR protects PostgreSQL state, including Storage metadata, but it does not version or replay the separate object bytes.

Can you use `storage.objects` as a file backup?

No. Those rows are an index of objects, not the object content. Restoring or editing them directly cannot recreate a missing PDF, image or upload.

Can you restore Storage to a new Supabase project?

Yes, if you retained an independent object copy and its manifest. Recreate compatible buckets first, upload objects to the original paths, then compare counts, sizes and hashes before application cutover.

What should a Storage backup manifest contain?

At minimum: bucket, complete object path, byte size, content type, checksum, capture time and the database recovery point it belongs to.

I build ReviveDB, which backs up Supabase projects outside Supabase, including Storage files. This post was first published on the ReviveDB blog.