Skip to content
ReviveDB
Blog

How to back up Supabase with the CLI

By AK

A Supabase CLI backup is a portable logical export of your PostgreSQL database. Supabase recommends taking roles, schema and data as three separate files. That gives you the pieces needed for a controlled database restore, but it is not a backup of every Supabase service in the project.

This guide follows the current Supabase backup and restore documentation. It also adds the part a successful dump cannot prove: that the files restore cleanly into an empty target.

Before you run the backup

  • Install the Supabase CLI and Docker Desktop. The CLI uses a containerized pg_dump.
  • Open Connect in the Supabase dashboard and choose the session pooler connection string on port 5432. Use the direct connection only when your network supports IPv6 or the project has the IPv4 add-on.
  • Keep the database URL in a secret or environment variable. It contains a password and must not be committed with the backup files.

Supabase documents these prerequisites in Backup and Restore using the CLI. Check that page again when automating the commands because the exclusions and restore notes can change with the platform.

Create the three backup files

Set SUPABASE_DB_URL in the environment used by your terminal or job runner. Then create a directory that is not served publicly and run the three dumps:

supabase db dump --db-url "$SUPABASE_DB_URL" -f roles.sql --role-only
supabase db dump --db-url "$SUPABASE_DB_URL" -f schema.sql
supabase db dump --db-url "$SUPABASE_DB_URL" -f data.sql --use-copy --data-only -x "storage.buckets_vectors" -x "storage.vector_indexes"

roles.sql

This records database roles separately from the objects they own. Custom login-role passwords are not recoverable from the dump and must be set again on the target.

schema.sql

This contains the database structure: tables, functions, policies, indexes and other schema objects included by the Supabase CLI. If you changed Supabase-managed auth or storage schemas, the official guide calls for a separate schema diff.

data.sql

This contains the rows and uses COPY for a faster restore. The two vector Storage tables are excluded in the current Supabase example because their data is rebuilt separately.

Store the result outside the project

Move the files to encrypted storage outside the Supabase project and outside the machine that ran the command. A dump left on a laptop is vulnerable to the same loss, theft or ransomware event as the laptop. Do not commit production data to a Git repository, even when the repository is private.

  • Encrypt the archive before upload and keep the encryption key elsewhere.
  • Record the backup time, CLI version and source PostgreSQL version.
  • Set retention deliberately and alert when an expected backup is missing.

Test the restore

File size and a zero exit code are useful checks, but neither proves the dump is usable. Restore into a new, isolated target and make the first SQL error stop the operation:

psql \
+  --single-transaction \
+  --variable ON_ERROR_STOP=1 \
+  --file roles.sql \
+  --file schema.sql \
+  --command 'SET session_replication_role = replica' \
+  --file data.sql \
+  --dbname "$TARGET_DB_URL"
  1. Check that the command completed without ignored SQL errors.
  2. Compare expected schemas, extensions, tables and row counts with the source.
  3. Test a representative application query and an Auth flow against the recovery target.
  4. Record the restore duration, then destroy the isolated target.

For a fuller verification procedure, see how to test a PostgreSQL backup. ReviveDB performs this database restore test for every recovery point.

What the CLI database dump does not back up

Supabase Storage files

The database keeps Storage metadata, not the object bytes. Copy the files separately and retain bucket configuration plus a manifest of paths, sizes and checksums. The practical steps are in how to back up Supabase Storage files.

Edge Functions and project settings

Function bundles, Auth provider settings, redirect URLs, Realtime settings, API keys and external integrations are not recreated by these three database files. Keep Function source in version control and maintain a recovery inventory for settings and secrets.

The project encryption root key

Vault and encrypted-column data in the dump remains ciphertext. Supabase warns that a manual restore into a new project needs the old project root key to decrypt it. Retrieve and handle that key through the documented recovery flow before the old project is paused or deleted.

The short version

Use the supported roles, schema and data commands, store the results independently, and restore-test them. Then protect Storage bytes, Functions and configuration as separate assets. That turns a database export into a recovery plan for the application rather than a collection of files.

If you do not want to maintain the schedule, off-platform storage and restore test yourself, ReviveDB backs up the complete Supabase project and reports the verification status of each component.