The problem
A database dump is not the same as a recovery plan for a hosted Supabase project. Data and configuration can also live in Storage, Auth, Edge Functions, API keys, Vault, and other platform surfaces, while some values cannot be exported or recreated identically through Supabase's public interfaces.
pgDumpster is designed not to hide those gaps. If something cannot be exported, verified, or restored automatically, it is reported as a platform or manual limitation instead of being silently treated as a complete backup.
Product goals and requirements
The goal is a verifiable recovery process for one hosted Supabase project where the backup material can be moved, inspected and validated before a restore.
The implemented coverage includes:
- Database backup and restore with explicit handling of managed and non-portable state
- Storage catalog plus streamed object capture
- Auth, SSO, Third-party Auth and API-key coverage with platform-limit semantics
- Edge Function source-tree capture and deployment to the target
- Encrypted
.tar.zst.ageoutput usingage - SHA-256 verification plus offline inspect, coverage and verify
- Checkpoints, resume and drift detection across the backup flow
- Local and S3-compatible destinations
- Restore dry-run, immutable restore plan, checkpointed executor and parity report
- JSON output and non-interactive operation for CI
The solution
pgDumpster is a CLI that creates a portable, inspectable backup bundle. The backup flow records coverage across supported surfaces, verifies integrity and can later build a restore plan against a separate fresh target project.
The normal recovery path is staged: doctor, backup, offline verify/coverage/inspect, restore dry-run and only then an explicit restore --apply.
Key technical decisions
Fail-closed coverage
Missing export or restore coverage is not treated as success. Limitations caused by Supabase's public interfaces or requiring manual handling receive an explicit coverage result. That is part of the product contract and prevents an incomplete backup from being presented as complete.
Restore as separate stages
Verification, inspection and the restore plan come before the explicit restore --apply. The restore plan is immutable and can be inspected as a separate part of the flow before the executor applies it to the target project.
Integrity and encryption
Backup output can be encrypted as .tar.zst.age, and SHA-256 verification is used for integrity checking. Offline verify, coverage and inspect can therefore run against the produced bundle without starting a restore.
Validation and current status
v0.1.2 is published as an npm package and can be installed as a global CLI. The exact release SHA passed repository CI, CodeQL, official-contract drift and a protected hosted source-to-target E2E before publication.
The live recovery test completed an encrypted backup, offline verification and restore to a clean target with 55 terminal coverage components. The result also reported platform limitations that cannot be recreated automatically.
Product website and documentation
The product website is structured as a technical introduction to the tool, focusing on coverage, recovery limits, prerequisites, workflow and licensing. The same information hierarchy is adapted for mobile viewports.
Install the CLI from npm:
npm install -g pgdumpster
pgdumpster --version
- pgdumpster.com — product website and introduction
- GitHub repository — source, documentation, issues and releases
- npm: pgdumpster — published CLI package
License and boundaries
pgDumpster is source-available under the PolyForm Shield License 1.0.0. Internal and non-competing use is permitted under the license terms; operating a competing hosted, managed or white-label backup service requires a separate commercial license.
The project is independent of Supabase and is not affiliated with, sponsored by or maintained by Supabase.