Back up a Supabase database

To back up a Supabase database with SupaCove, register the project's session pooler connection string, set a cron schedule, and keep the age identity offline. Each run is a full pg_dump of the Postgres database, encrypted with age before it is written anywhere. You restore it with the recovery kit onto a PostgreSQL server that has Supabase's extensions.

What Supabase gives youCopy Anchor Link

Supabase's own documentation states that Free Plan projects do not get automatic backups and recommends exporting the data regularly and keeping off-site copies. Paid plans include daily backups: the last 7 days on Pro, 14 days on Team, and up to 30 days on Enterprise.

Source: Supabase — Database Backups, checked on 2026-10-08. Plans change; read the source before relying on these numbers.

SupaCove fills a different role on each side of that line:

• Free Plan: it is the scheduled backup the plan does not include.
• Paid plans: it is an additional copy that you hold yourself, outside the platform, encrypted with a key only you have.

What the backup containsCopy Anchor Link

Each backup is one full pg_dump of the Postgres database in custom format.

Before you startCopy Anchor Link

• A running SupaCove instance. The Quickstart takes you through building the image, starting it and creating the admin account.
• The age identity created and stored offline (Quickstart, step 4). Without it no backup can be decrypted.
• The Supabase database password.

Set it upCopy Anchor Link

Restore a backupCopy Anchor Link

A Supabase backup's recovery kit restores with its supabase profile. A full Supabase archive does not restore cleanly as it is, so the profile checks the target first and leaves out the archive entries that are known to fail.

What you needCopy Anchor Link

• A PostgreSQL server with Supabase's extensions and roles, such as the supabase/postgres image. Pick its major version from the manifest: at least backup.toolVersions.clientMajor, the major version of the pg_dump that wrote the archive. That is usually your project's own major version.
• A new, empty database on that server. Do not use the image's own postgres database, which already holds the Supabase schemas.
• A superuser connection. On the image that is supabase_admin. The postgres role cannot write to the vault tables.
• age, pg_restore, psql and sha256sum on the machine you run the kit from, with pg_restore at least clientMajor too.

Run the kitCopy Anchor Link

Download the recovery kit and the ciphertext for the job, then:

export PGPASSWORD='<superuser password>'
psql 'postgresql://supabase_admin@host:5432/postgres' -c 'CREATE DATABASE restored'

AGE_IDENTITY_FILE=/path/identity.txt \
sh restore-job7.sh 'postgresql://supabase_admin@host:5432/restored' backup-job7.dump.age

The kit verifies the ciphertext SHA-256 and refuses a non-empty target, as every kit does. With the supabase profile it also:

1. refuses a connection that is not a superuser, before decrypting;
2. reads the archive's extension list and stops, before writing anything, if the target server cannot install one of them, naming the missing ones;
3. leaves out the grant on graphql_public.graphql. That function is created by a Supabase event trigger and is not stored in the archive, so the grant has nothing to attach to;
4. runs pg_restore --exit-on-error on everything else, so any other error still stops the restore;
5. checks the table count against the manifest.

It prints how many entries it left out.

What we testedCopy Anchor Link

On 2026-10-08 we ran the whole path on the supabase/postgres:15.8.1.085 image: a database holding a table with row level security, grants to anon and authenticated, a vector column and a second schema was backed up by SupaCove, uploaded to S3-compatible storage, downloaded, and restored with its kit into a second server running the same image.

After the completed run the 500 test rows matched the source by checksum, row level security and its policy were in place, the grants to anon, authenticated and service_role were restored, and so were the auth tables and all eight extensions.

A hosted project's archive may hold entries this image does not produce. If the kit stops on one, read the pg_restore error it prints: the restore can still be finished by hand with age --decrypt and pg_restore --no-owner without --exit-on-error, reading every reported error before you trust the result.

Which backups get this profileCopy Anchor Link

Databases whose host is a Supabase address, and databases you registered with the platform set to Supabase. Register a self-hosted Supabase as Supabase to get it. SUPABACKUP_PROFILE=supabase or generic in the environment overrides the kit's default.

Details: Restore & disaster recovery.

Common problemsCopy Anchor Link

• The connection test fails or the job fails with network. Check that the string is the session pooler or the direct connection, not the transaction pooler on port 6543.
• The direct connection does not resolve. It is IPv6-only without the IPv4 add-on. Use the session pooler instead.
• The job fails with client_version. No bundled pg_dump matches the server's major version. The image ships clients for PostgreSQL 14 to 18; changing the host or port does not help.
• The kit says the target cannot install some extensions. Restore onto the supabase/postgres image, or install the named extensions first.
• The kit says it needs a superuser. Connect as supabase_admin on the image, not as postgres.
• pg_restore stops at unrecognized configuration parameter. The target server is older than the pg_dump that wrote the archive. Use a server of at least backup.toolVersions.clientMajor.

More: Troubleshooting.

What this does not doCopy Anchor Link

• It does not stop a project from being paused, and it cannot back up a database it can no longer connect to.
• The software is free. The machine that runs it, the object storage and the network transfer are not.