Restoring Backups

Learn how to restore your Supabase projects from backups when needed.

Before Restoring

Restoring overwrites existing data. Always verify you're restoring to the correct project.

Pre-Restore Checklist

• [ ] Confirm backup is the correct one
• [ ] Note the backup date and type
• [ ] Consider backing up current state first
• [ ] Stop the project before restore (recommended)
• [ ] Notify users of downtime

Restore via Web UI

1. Navigate to Backups
2. Find the backup to restore
3. Click Restore
4. Select restore options:
   • Project to restore to
   • What to restore (all or partial)
5. Confirm and start restore

Restore via API

Full Restore

Restore everything in the backup:

curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["full"]
  }'

Response:

{
  "success": true,
  "restore": {
    "backupId": "backup-123",
    "projectId": "my-project",
    "duration": 180,
    "restoredAt": "2026-01-19T12:00:00Z",
    "warnings": []
  }
}

Partial Restore

Restore specific components:

# Database only
curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["database"]
  }'

# Multiple components
curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["database", "storage"]
  }'

Available restore types:

• full - Everything
• database - PostgreSQL database
• storage - File storage
• functions - Edge functions
• config - Project configuration

Force Restore

Override safety checks:

curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["full"],
    "forceRestore": true
  }'

Force restore skips validation. Use only when you're certain about the restore.

Restore to Different Project

You can restore a backup to any project, not just the original:

Via Web UI

1. Navigate to Backups
2. Find the backup to restore
3. Click Restore
4. In the "Restore To" dropdown, select a different project
5. Select components to restore
6. Confirm and start restore

Via API

Specify targetProjectId to restore to a different project:

curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["database", "storage", "functions"],
    "targetProjectId": "new-project"
  }'

The target project must be running for database restore. Storage and functions can be restored regardless of project status.

Import from External Sources

To migrate from Supabase Cloud or import external backups, use the Import / Migrate feature:

1. Navigate to Backups → Import / Migrate
2. Select a target project
3. Upload files for each component:
   • Database: .sql, .dump, or .gz file
   • Storage: .zip or .tar.gz archive
   • Functions: .zip or .tar.gz archive

Via API

# Import database dump
curl -X POST https://supascale.example.com/api/v1/projects/my-project/import/database \
  -H "X-API-Key: your-api-key" \
  -F "[email protected]"

# Import storage files
curl -X POST https://supascale.example.com/api/v1/projects/my-project/import/storage \
  -H "X-API-Key: your-api-key" \
  -F "[email protected]"

# Import Edge Functions
curl -X POST https://supascale.example.com/api/v1/projects/my-project/import/functions \
  -H "X-API-Key: your-api-key" \
  -F "[email protected]"

See the Backups API documentation for full details.

Restore Encrypted Backups

Encrypted backups require the encryption password:

curl -X POST https://supascale.example.com/api/v1/backups/backup-123/restore \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "restoreTypes": ["full"],
    "encryptionPassword": "your-backup-password"
  }'

Restore Process

What Happens During Restore

1. Validation - Verify backup integrity
2. Stop project (if running)
3. Database restore - Import SQL dump
4. Storage restore - Copy files
5. Config restore - Update configuration
6. Start project (if was running)
7. Verify - Health checks

Estimated Restore Times

Verify Restore

After restore, verify:

1. Check Project Status

curl https://supascale.example.com/api/v1/projects/my-project/status \
  -H "X-API-Key: your-api-key"

2. Verify Database

Connect to database and check:

• Tables exist
• Row counts are expected
• Recent data is present

3. Check Storage

Verify files are accessible:

• List storage buckets
• Download a test file

4. Test Application

• Load your application
• Test key functionality
• Verify authentication works

Rollback

If restore causes issues:

1. If you backed up before restore, restore that backup
2. If not, check for earlier backups
3. Contact support if data loss occurred

Troubleshooting

"Backup not found"

1. Verify backup ID is correct
2. Check backup wasn't deleted
3. Ensure backup is accessible (cloud storage)

"Restore failed - database error"

1. Check PostgreSQL logs
2. Verify database version compatibility
3. Check for schema conflicts
4. Try database-only restore first

"Restore failed - permission denied"

1. Verify file permissions
2. Check disk space
3. Ensure Supascale has write access

"Project won't start after restore"

1. Check container logs
2. Verify configuration is valid
3. Check environment variables
4. Try manual start with logs

Disaster Recovery Plan

Recommended Steps

1. Regular backups - Daily full, hourly database
2. Off-site storage - Cloud storage in different region
3. Test restores - Monthly restore tests
4. Document process - Written recovery procedures
5. RTO/RPO targets - Define acceptable downtime/data loss

Recovery Time Objective (RTO)