# Restore a database

Build a new database from a database's backups, to the latest moment, to a second in the recovery window, or to the end of one backup.

A restore builds a **new** database from the source's backups; the source is untouched. A deleted
database whose backups are kept restores the same way. Replace _ewdb-0123456789ab_ with the source
database's id and _orders-restored_ with the new database's name.

**Important:**
The new database is billed like any other from the moment its machines are built.

## Prerequisites

- Permission for `rds:RestoreDBInstance` on the source database. When the new disks use a
  customer key (the source's, or the one you name), also `kms:Encrypt` on that key.
- At least one completed backup. Otherwise the request is refused with `409` "No backup of this
  database has completed, so there is nothing to restore from."
- For a `time` target, a moment inside the recovery window the backup list reports. Earlier than
  the window is refused with `400` "Nothing was kept for …", later than now with `400` "… is in
  the future". When only backups kept until deleted are left, only **The end of one backup** is
  accepted (`409`).
- A new name: the source's own name is refused with `400` "A restore builds a new database; give
  it a new name.", and a name in use with `409` "A database named "…" already exists".
- In `fi1`, the organization setting **Allow EU locations outside Germany** on at that moment
  (otherwise `403`).
- Room in the DB instances quota: the new database counts.
- In the console, also `rds:DescribeDBInstances` to open the source database's page (without it the
  page is not found).

## Restore

**Console**
1. Open the source database, then choose the **Backups** tab.
2. Choose **Restore…**. The **Restore to a point in time** dialog opens.
3. For **New database name**, enter orders-restored.
4. (Optional) Select **As a three-node cluster** (the machine type needs 8 GiB or more). It is
   cleared by default, even for a cluster source.
5. (Optional) Select **Reachable from the internet**. It is cleared by default, so a copy of a
   public database is never public without someone choosing it (the API instead takes the
   source's setting when you omit it).
6. Under the recovery target, choose **The latest moment available**, **A specific time (UTC)**
   (and enter it, to the second), or **The end of one backup** (and choose the backup).
7. Choose **Request restore**.

The dialog says what the new database is built as and what it costs a month. The request appears
under **Restore requests** with a link to the new database.

**CLI**
```sh
dcloud rds backups restore ewdb-0123456789ab --recovery-target time \
  --recovery-target-time 2026-09-07T12:00:00Z --target-identifier orders-restored
```

**API**
```http
POST /rds/api/instances/ewdb-0123456789ab/restore
{ "recoveryTarget": "time", "recoveryTargetTime": "2026-09-07T12:00:00Z", "targetIdentifier": "orders-restored" }
```

**Terraform:** not available. A restore is an action, not configuration.

`recoveryTarget` is `latest` (everything the repository holds), `time` (a moment inside the
recovery window) or `label` with `recoveryTargetLabel` (the end of one backup). `targetIdentifier`
names the new database; `instanceClass` defaults to the source's. `publiclyAccessible` decides
whether the copy answers on the internet; omitted, it takes the source's setting. `kmsKeyId` names
the key for the new disks; omitted, it takes the source's, and `null` uses the platform key.
`topology` is `single` unless you say `"cluster"`, whatever the source was.

**Granularity.** A `time` target can be any instant in the window, to the millisecond; the console
picks to the second. Recovery replays every transaction committed up to and including that
instant. A database archives its write-ahead log at least every five minutes, so the last few
minutes before a request may not be in the repository yet. Before reading the backups, a `time` or
`latest` restore therefore asks the source to archive what it holds (**Activity**: "Archived the
source's current WAL"), which makes everything up to the request recoverable. If the source cannot
be reached (stopped, or its machines are gone), recovery ends at the newest archived log, up to
five minutes before the request. **Activity** warns, and a `time` target inside that gap fails
rather than restoring to a different moment. A deleted database kept with its backups is restored
up to its final backup.

## Cancel a restore

While a restore is still `queued` (nothing has read it yet), you can withdraw it. It needs
`rds:RestoreDBInstance` on the **source** database, the same grant that created the request, and
the decision is recorded in the audit log.

**Console**
1. On the source database's **Backups** tab, under **Restore requests**, choose **Cancel**.

**CLI**
```sh
dcloud rds backups cancel-restore job-id
```

**API**
```http
DELETE /rds/api/restore-jobs/3f8b6c2e-1d4a-4b7e-9c2f-5a6b7c8d9e0f
```

**Terraform:** not available. A restore is an action, not configuration.

The job moves to `cancelled`, and the placeholder database the request had already created is
removed with it, so the name it was holding is free again. Nothing is removed if the target's
machines have already been created: a machine somebody is paying for is deleted as a database, not
dropped as a row. Once the job is `restoring`, the request is refused with `409` "This restore has
already started. It cannot be cancelled; delete the database it is building instead." Delete the
new database instead (`DELETE /rds/api/instances/{targetId}`).

## Result

The call returns `202` with the restore job and the target, which appears in the list as
`creating`. The target has the source's engine version, storage size, master username, database
name, network and retention, and the source's **parameter changes**, TLS-only setting and logical
replication. Its first machine replaces its data directory with the chosen backup and recovers to
the target before PostgreSQL first starts. On a cluster, the other two members then copy the
restored database from it. The source's master password opens the target, filed in Secrets for the
copy; rotating one does not change the other.

The job on `rds.backups.list-restore-jobs` moves through `queued`, `restoring` and `completed`
when the target is `available`, or `failed` with the reason, which is also the last **Activity**
line on both databases.

## Related

- [Back up a database](back-up-a-database.md)
- [Delete a database](delete-a-database.md): keep the backups with a final backup.
- `rds.backups.restore` · `dcloud rds backups restore`
