SOURCE-AVAILABLE · LOCAL-FIRST · EXPLICIT COVERAGE
Back up the recoverable parts of a Supabase project
pgDumpster packages one hosted Supabase project into a portable bundle with checksums, terminal coverage outcomes and documented restore limits.
It is a local CLI, not a pgDumpster SaaS: pgDumpster does not operate an account, hosted backup copy or proxy for your project data. You choose the environment and destination - local storage or configured S3-compatible storage - then review a deterministic restore plan before a target changes.
BACKUP RUN
discovering project resources
databaseaccounted for
storageaccounted for
edge functionsaccounted for
project configurationaccounted for
exporting applicable recoverable state
recording platform and manual limits
writing integrity and consistency evidence
result: complete, limits, or failed
WHAT IT IS
A database dump is not a project backup
PostgreSQL is only one part of a hosted Supabase project. Storage object bytes, Auth state, Edge Functions and applicable project configuration sit outside a conventional database dump.
pgDumpster captures the exportable project-scoped state it can reach, then reports what was captured, what was unavailable and what needs an operator procedure.
It never represents an unavailable value, a replacement credential or an external system as an identical automatic restore.
DATABASE-ONLY BACKUP
project └── PostgreSQL
PGDUMPSTER
hosted project ├── PostgreSQL ├── file storage ├── exportable Auth / API state ├── deployable Edge source ├── applicable configuration └── coverage + integrity evidence ↓ portable backup bundle
BACKUP COVERAGE
Know what the bundle contains - and what it cannot contain
Coverage is component-level, not a marketing label. pgDumpster records a terminal outcome for every registered component, including `not_exportable` and `failed`.
| Area | What pgDumpster captures | Restore expectation |
|---|---|---|
| PostgreSQL | Logical database state, roles, schema, data, migrations and supported extension state. | Exact or semantic, per component |
| File Storage | Bucket configuration, object bytes and supported metadata. | Bytes are checksum-verified |
| Auth and API | Exportable Auth data/configuration, provider configuration and API-key definitions. | Private material and replacements have limits |
| Edge Functions | Deployable source trees, deployment metadata and a secret inventory. | Source is deployable; secret values can be unavailable |
| Control plane | Applicable project and service configuration, plus capability evidence. | Restored only where a current documented write contract and handler exist |
| Verification | Manifest, coverage, checksums and consistency evidence. | Inspectable offline |
A successful backup can still be complete_with_platform_limits. Read the coverage report before relying on it for recovery.
RECOVERY LIMITS
Deliberate recovery, not an identical-project promise
pgDumpster is designed to make limitations visible. These limits are part of a correct recovery decision, not hidden footnotes.
No atomic project snapshot
Supabase does not expose one transaction spanning PostgreSQL, Storage, Edge Functions and Management APIs. `verified` is pgDumpster's application-level stabilization mode, not a platform-wide atomic snapshot.
No silent completeness claim
Every registered component gets a terminal coverage outcome. A result can be `complete_with_platform_limits`; it is not an identical-project claim.
Private or platform-held material
Private Auth signing material, some Edge secret values and other values Supabase does not return stay explicit manual/platform actions.
Replacement rather than equality
When a target API generates a new secret, pgDumpster records the required protected rotation mapping. It does not call a different secret an identical restore.
External systems stay external
DNS, SMTP, OAuth-provider resources, source Git repositories, organization membership and billing are outside a single hosted-project backup.
Some platform surfaces are manual
Analytics/Iceberg data, read-only PgBouncer, backup schedules, custom/vanity domains, disk/autoscale, add-ons, read replicas, log drains, PrivateLink and JIT access remain explicit platform limits until a supported write contract and handler exist.
Read the generated restore plan, manual actions and parity report for the actual source bundle. Those artifacts are more specific than this overview.
BEFORE YOU INSTALL
Access and runtime requirements are real prerequisites
pgDumpster is intended for operators who control the source project and the backup destination. The CLI checks access, dependencies and project health with doctor, but a passing install alone is not a recovery drill.
Runtime
Node.js >=22.15.0 <23 or >=24 <25, Supabase CLI >=2.111.0 <3.0.0, and a reachable Docker-compatible daemon for the current database workflow.
Source access
A Supabase Management API access token, a linked workspace or database URL, and a privileged Storage credential that pgDumpster can prove suitable.
Destination
Local storage or configured S3-compatible storage. Cloudflare R2 has live interoperability evidence; do not assume every provider has identical evidence.
Encryption
The `age` executable plus a recipient for encrypted backups; an identity file is required to read an encrypted archive.
INTO - AND OUT OF - THE DUMPSTER
Discover. Back up. Verify. Plan. Apply deliberately.
Discover
Identify the project resources the authenticated operator can access.
Back up
Capture applicable exportable state, then produce coverage and integrity evidence.
Verify
Inspect coverage and validate the bundle offline before trusting it.
Restore
Create a deterministic plan first. `--apply` is required for mutation and blocked work does not modify a target.
The disposable source-to-clean-target recovery flow passed as a local live E2E and as protected exact-SHA release evidence for v0.1.2. CI runner setup is environment-specific; validate your normal local recovery path and any scheduler independently.
RESTORE SAFETY
A restore is a reviewed plan, not a one-click rollback.
Before mutation, pgDumpster verifies the bundle, builds a deterministic plan and rejects source=target. A blocked plan fails before target credential or resource discovery; an executable plan still requires explicit --apply. There is no automatic cross-service rollback, no automatic project deletion and no claim that manual/platform limits were restored.
YOUR INFRASTRUCTURE
The backup stays on your side.
pgDumpster runs where you run it and writes to local storage or an S3-compatible destination you configure. MKP Digital does not receive a copy of your backup data through this tool or website.
SOURCE AVAILABLE
Source available, with explicit licensing boundaries
pgDumpster is distributed under the PolyForm Shield License 1.0.0. It is not OSI open source. The public license governs permitted use; competing hosted, managed, white-label or commercial backup services require a separate written commercial license.
Commercial terms and pricing are provided on request; the public repository's LICENSE and NOTICE files are authoritative.
TEST RECOVERY, NOT JUST BACKUP
Start with the CLI. Trust it after a recovery drill.
Install the public CLI, run doctor, create an encrypted verified backup, verify it offline, inspect its coverage and restore it to a fresh test target before relying on it for disaster recovery.