Backups and restores
Backups and restore flows exist for the moments when confidence and correctness stop matching.
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 listA 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.
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 listRestore targets
A restore references one source — a backup key, a PITR timestamp, or a restore point — and lands in one of three targets:
| Target | Behavior |
|---|---|
new_preview (default) | Creates a fresh preview database with the restored state. Safest; nothing existing is touched. |
preview | Overwrites an existing preview database. |
project | Overwrites the project database. Requires the explicit confirmation flag and the org admin role. |
# 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 --waitA project overwrite is the one genuinely destructive operation in the product, which is why it demands --confirm-project-overwrite (or confirm_project_overwrite: true in the API) and an org admin role when called with a session. 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?".