Ciroc0/pgdumpster: Backup, inspect, verify, and restore Supabase projects with explicit coverage and restore-safety limits.

Backup, inspect, verify, and restore Supabase projects with explicit coverage and restore-safety limits. - Ciroc0/pgdumpster

Summary

pgDumpster is a TypeScript CLI for backing up, verifying, inspecting, and restoring a single hosted Supabase project. It treats a PostgreSQL dump as one part of recovery, also covering project configuration, Storage, Auth, Edge Functions, API keys, and Vault. When Supabase withholds state that cannot be recreated exactly, the tool reports that as a platform or manual limit rather than claiming full recovery.

What it is useful for

The tool fits engineers who need disaster-recovery workflows for Supabase projects and want explicit reporting on what each backup does and does not cover. It produces age-encrypted .tar.zst.age archives that can be verified offline, and it supports dry-run restores against a fresh target project before any destructive action. The coverage command reports a terminal outcome per registered component, and restore --apply fails before mutation if any planned action has no supported restore handler.

Documented limits include: only one project ref is backed up at a time; organization membership, billing, external DNS/SMTP/OAuth, source Git repositories, and previously deleted Storage versions are out of scope. Each branch or environment with its own data must be backed up separately. The default verified consistency mode is described as an application-level stabilization check, not a single Supabase-wide transaction. A complete_with_platform_limits or restored_with_platform_limits outcome requires reviewing the listed manual actions.

How engineers can use it

The README documents a clear path. Prerequisites are Node.js >=22.15.0 <23 or >=24 <25, Supabase CLI >=2.111.0 <3.0.0, a Docker-compatible daemon, and age. Install with npm install -g pgdumpster, or from a source checkout via corepack enable and pnpm install --frozen-lockfile followed by pnpm build.

Set session environment variables for PGDUMPSTER_PROJECT_REF, PGDUMPSTER_ACCESS_TOKEN, PGDUMPSTER_DB_URL, and PGDUMPSTER_STORAGE_KEY; doctor currently requires all four. Copy examples/backup.config.example.yaml to pgdumpster.yaml and configure an age recipient and identity file, then run pgdumpster doctor. Back up with pgdumpster backup --config ./pgdumpster.yaml --project-ref $ref --linked (or --db-url-env PGDUMPSTER_DB_URL for unlinked sources). Use the printed path with verify, coverage, and inspect, then run restore --dry-run against a different target project before considering --apply. Plaintext output requires --allow-plaintext-secrets. The project is source-available under the PolyForm Shield License 1.0.0; the full CLI contract lives in docs/07-cli-and-ux.md.