Back up a database
Take a backup now, change the retention period and backup window, and delete a backup you took by hand.
Every database with backupRetentionDays above 0 takes a full backup once a day inside its backup
window, and archives write-ahead log continuously between backups. Both go from the database
machine straight to object storage, encrypted on the machine; nothing passes through the console.
The primary starts the first full backup when it has finished setting up. Replace ewdb-0123456789ab with
your database's id.
Prerequisites
rds:CreateBackupto take one,rds:DeleteBackupto delete one,rds:ModifyDBInstanceto change the settings,rds:ListBackupsto list them.- In the console, also
rds:DescribeDBInstancesto open the database's page (without it the page is not found).
Take a backup now
- Open the database, then choose Backups.
- Choose Back up now.
dcloud rds backups create ewdb-0123456789abPOST /rds/api/instances/ewdb-0123456789ab/backupsNot available in Terraform. A backup is an action, not configuration.
The call returns 202 with state: "requested" and the new backup row (status running; the
console shows Requested). The machine picks the request up within a minute, and the row moves
to completed with a pgBackRest label, the size backed up, the size it occupies in the repository,
and the WAL range it needs. The request is refused with 409:
- while the database is not
available: "A database in status "status" has nothing running to back up"; - while another backup is outstanding: "A backup requested at time has not reported back yet";
- when no backup agent has reported from its machines (below);
- when it already keeps 20 backups taken by hand: "This database already keeps 20 backups taken by hand. Delete one under Backups first."
In the console, Back up now is not offered on a database deleted with a final backup, and when it cannot run, the reason is written under the button.
A backup you take by hand is kept until you delete it (keptUntilDeleted: true on the row), at
most 20 per database; the daily ones follow the retention period. A kept backup older than the
period restores to its own end (The end of one backup, recoveryTarget: "label"), not to the
moments around it: only the write-ahead log that makes it consistent is kept with it. After the
database is deleted with a final backup, its kept backups stay until you delete them.
keepsByHand in the backup list says whether a database does: its machines must run the current
backup scripts. On a database whose machines are older, a backup taken by hand follows the
retention period, and the tooltip of Back up now says so, until its machines' backup scripts
are replaced.
Delete a backup you took by hand
- On the Backups tab, open the actions menu of a completed backup you took by hand and choose Delete backup. Other backups have no menu.
- Choose Delete backup to confirm.
dcloud rds backups delete ewdb-0123456789ab backup-idDELETE /rds/api/instances/ewdb-0123456789ab/backups/3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0fNot available in Terraform. A backup is not a Terraform resource.
Older than the retention period, it is removed from the repository within a minute (on a database
deleted with a final backup, it goes with the other kept backups). Inside it, it stays until the
period passes it, like a daily one. A backup that follows the period anyway is refused with 409
"This backup follows the retention window and goes with it; only a backup kept until deleted is
deleted by hand."; an unknown one with 404 "No such backup of this database."
Change retention or the backup window
Not available in Console. The database's overview shows **Backup retention** and **Backup window**; changing them is in the CLI, API and Terraform.
dcloud rds instances modify-backup-settings ewdb-0123456789ab \
--backup-retention-days 14 --backup-window 02:00-03:00PATCH /rds/api/instances/ewdb-0123456789ab/backup-settings
{ "backupRetentionDays": 14, "backupWindow": "02:00-03:00" }resource "dcloud_db_instance" "orders" {
identifier = "orders"
instance_class = "performance-2"
backup_retention_days = 14
backup_window = "02:00-03:00"
}The machine applies the change within a minute. Retention 0 stops the daily backup; a request
through the API still works.
How backups work
| Property | Value |
|---|---|
| Tool | pgBackRest on the database machine |
| Repository | the database's own bucket in the platform's backup object storage; deleted with the database |
| Encryption | AES-256-CBC, client-side on the machine, one passphrase per database held by the control plane; fixed for the life of the repository. Databases created before this have none |
| Daily backup | one full backup, started within 45 minutes of the window start |
| WAL archiving | continuous; a segment is handed over when full or after five minutes (archive_timeout = 300) |
| Compression | zstd |
| Retention | full backups kept for backupRetentionDays; WAL kept as long as a backup that needs it |
backupRetentionDays |
0–35; 0 disables the daily backup |
backupWindow |
HH:MM-HH:MM in UTC; the start is what is used; default 03:00-04:00 |
| Cluster | the current leader takes the backup; a standby does nothing |
| Recovery window | the backup list reports recoveryWindow.earliest and .latest: from the end of the oldest completed backup inside the retention period to now |
The machine polls for work once a minute, and that poll is its heartbeat: agentSeenAt in the
backup list. A report about a backup it ran counts as the same heartbeat, so a request made straight
after the first backup at boot is not refused for want of a poll that is still a minute away.
A database created before backups existed has no backup agent on its machines: the list reports
agentSeenAt: null, a request is refused with 409, and the page says so until its machines
report in. A backup row has status running, completed, failed or expired. A failed row
carries the last lines of pgBackRest's output in error. A daily sweep marks a backup older than
the retention period expired, with the event "n backups aged out of the N-day retention
window"; pgBackRest on the machine removes the files itself.
Every backup is a full backup; there are no differential or incremental ones. A snapshot is a backup: capturing a database now is Back up now, and going back to it is a restore to The end of one backup.
Related
- Restore a database
- What runs on your machines: the credential and keys a database machine holds for its backups.
POST /rds/api/instances/{id}/backups·dcloud rds backups create·PATCH /rds/api/instances/{id}/backup-settings