Quick Supabase Backup Manager

Create, schedule, validate, and restore Supabase database backups with automated integrity verification.

When to Use This Command

Run this command when you need to:

• Create an on-demand database backup before a risky migration or schema change
• Configure automated backup schedules with retention policies and storage management
• Validate backup integrity and test restore procedures in a safe environment

Consider alternatives when:

• You need Supabase's built-in daily backups for Pro plan projects (those run automatically)
• You want to clone an entire Supabase project including auth and storage (use Supabase CLI branching)

Quick Start

Configuration

Copy
name: quick-supabase-backup-manager
type: command
category: database

Example Invocation

Copy
claude command:run quick-supabase-backup-manager --action backup --project myapp-prod --compress

Example Output

[Connect] Supabase project: myapp-prod (us-east-1)
[Backup] Starting full database export...
  Tables: 42 | Views: 8 | Functions: 15
  Export size: 284 MB (compressed: 67 MB)
  Duration: 1m 42s
[Verify] Integrity check: checksums match (SHA-256)
[Store] Backup saved: backups/myapp-prod-20260315-081200.sql.gz
[Retain] Active backups: 7 (policy: keep last 7 days)
[Cleanup] Removed 2 expired backups

Core Concepts

Backup Management Overview

Aspect	Details
Backup Types	Full export (pg_dump), incremental (WAL archiving), schema-only
Storage	Local filesystem, S3-compatible storage, or Supabase Storage buckets
Validation	SHA-256 checksum verification and test-restore on disposable instance
Scheduling	Cron-based automation with configurable retention windows

Backup Workflow

[Select Project + Scope]
         |
[pg_dump via Supabase connection]
         |
[Compress + Checksum]
         |
[Store + Apply Retention Policy]
         |
[Optional: Test Restore]
         |
[Report + Notify]

Configuration

Parameter	Type	Default	Description
action	string	backup	Operation: backup, restore, validate, schedule, or cleanup
project	string	required	Supabase project reference or ID
compress	boolean	true	Compress backup output with gzip
retention	number	7	Number of days to retain backups before cleanup
storage	string	local	Backup destination: local, s3, or supabase-storage

Best Practices

1. Backup Before Every Migration - Invoke a full backup immediately before running any migration command. This gives you a guaranteed restore point if the migration introduces data corruption.

2. Test Restores Regularly - A backup that cannot be restored is worthless. Schedule weekly restore tests against a disposable Supabase instance to verify backup integrity end-to-end.

3. Encrypt Sensitive Backups - Database exports contain raw data including user PII. Use GPG or AES encryption before transferring backups to external storage or sharing with team members.

4. Monitor Backup Storage Costs - Compressed full backups accumulate quickly for large databases. Set retention policies aggressively and archive older backups to cold storage tiers.

5. Separate Schema and Data Backups - Keep schema-only backups alongside full backups. Schema-only exports are small, fast, and invaluable when you need to recreate the database structure without data.

Common Issues

1. Connection Timeout on Large Databases - Databases over 1 GB may timeout during export. Increase the connection timeout with --timeout 600 or use incremental backups for very large datasets.

2. Restore Fails Due to Role Mismatch - Supabase backups reference specific roles (e.g., supabase_admin). When restoring to a different project, use --no-owner to skip role assignments.

3. Disk Space Exhaustion During Export - Full uncompressed exports can be 5-10x the database size. Always enable compression and verify available disk space before starting a backup.