Skip to content

Self-hosted · PostgreSQL · age encryption

SupaCove runs pg_dump against your managed PostgreSQL, encrypts the stream and stores it in S3-compatible object storage you own. Failures are explicit, and a restore does not depend on the instance.

QuickstartSee how restores work

Aiven, Prisma Postgres, TigerData, Miget and Render connect as standard PostgreSQL; not yet tested by us

01Features

Every feature, one page of docs.

Browse all docs →

age encryption, keys stay with you

X25519 + ChaCha20-Poly1305. By default the instance stores only the recipient; the identity stays offline with you

manual only→0 3 * * *

Cron schedules and freshness

Five-field cron or @daily aliases, IANA time zones; past the threshold, protection is EXPIRED

  1. retry 130s
  2. retry 260s
  3. retry 3120s
  4. retry 4240s

Webhooks, at least once

Three events through an outbox, retried with backoff, marked dead when exhausted

Dead-man switch

A ping after each successful, fresh backup, /fail on failure; your external monitor alerts on silence

Managed or self-hosted, one flow

Supabase, Neon and Railway get dedicated connection hints; Aiven, Prisma Postgres, TigerData, Miget and Render register as self-hosted/other

SB_VERIFY_ENABLED

Embedded restore verification

A real restore into embedded PostgreSQL after each successful backup; off by default, and enabling it gives the instance an identity file

02Encryption

The private key appears once, and you keep it offline.

Backups are encrypted with age while they are being dumped. By default the instance keeps the public recipient only; the identity that decrypts them stays offline with you.

  • Built-in age libraryX25519 + ChaCha20-Poly1305, with no external age CLI
  • Recipient only, by defaultThe instance keeps the public recipient. The one exception is restore verification, which hands the running instance an identity file
  • Lose the identity, lose the backupsidentity.txt is the only key that can decrypt them. Store it offline, encrypted
Create the age identity →

03Quickstart

Three commands to a running instance.

Build the image, start the container, claim the one-time token. Then create the age identity, register a database and take the first backup, and finally prove the restore.

Follow all six steps →

quickstart01–03 / 06

# 1. build the imagedocker build --target runtime -t supabackup:local .# 2. run itdocker run -d --name supabackup \  -p 127.0.0.1:8080:8080 \  -v supabackup-data:/app/data \  supabackup:local# 3. initialize the admin accountdocker exec supabackup /app/supabackup bootstrapOne-time bootstrap token (valid 15m0s):   jkwioY…
  1. Then
  2. 04Create the age identity
  3. 05Register a database and back it up
  4. 06Prove the restore

04Pipeline

One backup, six stages.

A failure in export, encryption or commit lands the job as failed. Verification and notification carry their own status: a failed verification leaves the job result alone, and exhausted deliveries are marked dead.

  1. 01

    Export

    pg_dump --format=custom

  2. 02

    Encrypt

    age stream encryption, X25519 + ChaCha20-Poly1305

  3. 03

    Stage

    atomic local commit: .inprogress → final name

  4. 04

    Upload

    with a destination configured: remote object-storage commit, read-back hash check

  5. 05

    Verifyoptional

    a real restore into embedded PostgreSQL

  6. 06

    Notify

    webhooks through an outbox, with retries

Lose the instance, keep the backups.

The metadata database is not a prerequisite. The manifest describes itself: server version, table count, SHA-256 and recipient fingerprint.

*.dump.ageciphertext, with its manifest
+
identity.txtoffline age identity
+
restore.shrecovery kit
=
your databasepg_restore
  1. 01verify ciphertext SHA-256
  2. 02refuse a non-empty target
  3. 03age decrypt
  4. 04pg_restore
  5. 05check the table count if the manifest has one
Restore & disaster recovery

05Guarantees

Four guarantees, no asterisks.

  1. 01

    Failures never look like success

    Any failure in export, encryption or commit lands the job as failed — never as succeeded.

  2. 02

    Restarts converge

    Shutdown-interrupted jobs are recorded as interrupted, with no false failure alerts. When the resume conditions hold, startup re-uploads automatically; otherwise the job keeps an explainable terminal state and the next scheduled run resumes the chain.

  3. 03

    Backups restore standalone

    Recovery needs exactly three things: the ciphertext, your offline age identity, and the recovery kit script.

  4. 04

    Secrets never leak into errors

    Passwords and credentials are redacted across logs, API errors, task history and metrics.

06FAQ

Short answers first.

Does the Supabase Free Plan include backups?
Supabase's documentation states that Free Plan projects do not get automatic backups and recommends exporting data regularly and keeping off-site copies. SupaCove does that on a cron schedule.Supabase documentation · checked 2026-10-08
How is this different from the platform's own backups?
Platform backups stay on the platform. A SupaCove copy is encrypted before it is written, lands in object storage you own, and is decrypted with a key you keep offline. Restoring it does not need this instance.
Does a backup include files in Supabase Storage?
No. A backup is one full pg_dump of the Postgres database: it includes auth user records and storage object metadata, but not file contents, Edge Function code or project settings.
What do I need to restore?
The ciphertext with its manifest, your offline age identity, the recovery kit script, and an empty PostgreSQL database. A Supabase backup restores onto a server that has Supabase's extensions; the Supabase guide has the steps.
Which platforms are supported?
Supabase, Neon and Railway get dedicated connection hints. Aiven, Prisma Postgres, TigerData, Miget and Render are standard PostgreSQL and register as self-hosted/other; we have not tested them ourselves yet. CockroachDB is not supported.

07Contents

Every page, in reading order.

  1. 01What is SupaCoveSelf-hosted encrypted PostgreSQL backups with BYOS storage and verifiable restores
  2. 02QuickstartBuild the image, initialize the instance, register a database, take the first encrypted backup
  3. 03InstallationImage, source build and deployment topology; compose is development-only
  4. 04ConfigurationEvery SB_* variable: defaults, semantics, risks
  5. 05Registering databasesConnection-string rules, per-platform gotchas, roles and TLS modes
  6. 06Storage destinationsSend encrypted backups to your own S3, Cloudflare R2 or Backblaze B2 bucket, from the console or through the API
  7. 07Schedules & retentioncron schedules, freshness thresholds, pause semantics, retention policy
  8. 08Dead-man switch (heartbeat)External monitoring integration: success ping, fail ping, age gate, disabling
  9. 09Notification webhooksThree events, outbox retry semantics and the delivery log
  10. 10Backups & downloadsTask state machine, the three download forms, failure semantics
  11. 11Restore & disaster recoveryRecovery kits, standalone restores without the metadata database, and the three key incidents
  12. 12Monitoring & metrics/metrics semantics, dashboard denominators, alerting suggestions
  13. 13TroubleshootingFrequent issues: login, pooling, resume, staging, verification, webhooks

Guides

  1. 01Back up a Supabase databaseScheduled, encrypted pg_dump backups of a Supabase Postgres database with SupaCove, what they contain, and how to restore one

Next

Restore it once,then trust it.

The quickstart has six steps, and the last one restores the backup you just took into a fresh database with the recovery kit. Do it once.

QuickstartRestore & disaster recovery
Bundled clients
PostgreSQL 14–18
Cipher
X25519 + ChaCha20-Poly1305
Storage
S3 / R2 / B2 / MinIO
License
AGPL-3.0