Back up a database

Take a backup now, change the retention period and backup window, and delete a backup you took by hand.

Last updated 18 November 2026View as Markdown

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

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

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

  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.

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.

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.

Did this page help you?