# 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:CreateBackup` to take one, `rds:DeleteBackup` to delete one, `rds:ModifyDBInstance` to change
  the settings, `rds:ListBackups` to list them.
- In the console, also `rds:DescribeDBInstances` to open the database's page (without it the page is
  not found).

## Take a backup now

**Console**
1. Open the database, then choose **Backups**.
2. Choose **Back up now**.

**CLI**
```sh
dcloud rds backups create ewdb-0123456789ab
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/backups
```

**Terraform:** not available. 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

**Console**
1. 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.
2. Choose **Delete backup** to confirm.

**CLI**
```sh
dcloud rds backups delete ewdb-0123456789ab backup-id
```

**API**
```http
DELETE /rds/api/instances/ewdb-0123456789ab/backups/3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f
```

**Terraform:** not available. 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

**CLI**
```sh
dcloud rds instances modify-backup-settings ewdb-0123456789ab \
  --backup-retention-days 14 --backup-window 02:00-03:00
```

**API**
```http
PATCH /rds/api/instances/ewdb-0123456789ab/backup-settings
{ "backupRetentionDays": 14, "backupWindow": "02:00-03:00" }
```

**Terraform**
```hcl
resource "dcloud_db_instance" "orders" {
  identifier            = "orders"
  instance_class        = "performance-2"
  backup_retention_days = 14
  backup_window         = "02:00-03:00"
}
```

**Console:** not available. The database's overview shows **Backup retention** and **Backup window**; changing them is in the CLI, API and Terraform.

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](restore-a-database.md)
- [What runs on your machines](what-runs-on-your-machines.md): the credential and keys a database
  machine holds for its backups.
- `rds.backups.create` · `dcloud rds backups create` · `rds.instances.modify-backup-settings`
