Backups and restores

On-demand backups

Creating a backup records a backup job against the project and stores the resulting backup key once the job completes. From the dashboard, the CLI, or the API:

capydb backups create --label "before-the-big-migration" --wait
capydb backups list

A backup.completed webhook event fires when the job finishes.

Scheduled backups

Each project can have a daily backup schedule: a UTC hour and minute, an active flag, and a retention window of 1 to 365 days. Backups older than the retention window are cleaned up automatically. Configure it from the project's Backups tab or PUT /v1/projects/{id}/scheduled-backups/default.

Exports (download your data)

An export is a downloadable pg_dump custom-format archive of the project database - your data, in a standard Postgres format any tooling can restore with pg_restore. Exports run as jobs and stay downloadable for 7 days, after which the artifact is deleted.

# Queue an export, wait for it, and download it in one step
capydb export

# Re-download a recent export
capydb export list
capydb export download --export <id>

From the dashboard, the Backups tab's Export button does the same and lists downloadable exports. Download URLs are short-lived and presigned - request a fresh one per download. An export.completed webhook event fires when the export job finishes.

Backups and exports serve different jobs: backups are the platform's restore anchors (verified, retained by schedule, restorable in place), while an export is a portable copy for your own tooling, offline analysis, or moving data elsewhere.

Point-in-time recovery

Regions with continuous-archiving storage expose point-in-time restore by RFC 3339 timestamp through the same restore surface. The project's region info shows whether PITR is available. The mechanics - window size, what bounds it, and how long restores take - are in Disaster recovery.

Restore points

A restore point is a label pinned to either a specific backup key (kind: backup) or a timestamp (kind: pitr, defaults to "now"). Pin one before risky work so the rollback target has a name instead of a timestamp you have to reconstruct later:

capydb restore-points create --label "pre-launch" --kind pitr
capydb restore-points list

Restore targets

A restore references one source - a backup key, a PITR timestamp, or a restore point - and lands in one of three targets:

# Inspect a backup in a throwaway preview
capydb restore --backup-key <key> --preview-name inspect-monday --ttl-hours 24 --wait

# Roll the project itself back to a point in time (destructive, gated)
capydb restore --restore-time 2026-06-09T14:30:00Z \
  --target-kind project --confirm-project-overwrite --wait

A project overwrite is the one genuinely destructive operation in the product, which is why it demands a single-use approval token and an org admin role when called with a session. The CLI handles this for you after --confirm (or the interactive type-the-name prompt); over the API, mint the token with POST /v1/projects/{projectID}/approvals ({"action": "project.restore_overwrite"}) and pass it as approval_token - it is valid for 10 minutes, works exactly once, and re-presenting a used token returns the restore job it authorized instead of restoring twice. restore.completed fires as a webhook event afterwards, and connected deployment integrations re-push env vars.

A restore replays a past state of production. If what you want in production is the current state of a preview you prepared - a rehearsed migration, a cleaned dataset - that is a cutover, not a restore.

Recommended habit

Restore into a preview first, look at the data, then decide whether to overwrite. The preview costs nothing permanent and removes the guesswork from "is this the right backup?".