rds.backups.restore

Restore to latest, to a timestamp, or to a labelled backup

POST /rds/api/instances/{id}/restoreIAM rds:RestoreDBInstanceChanges stateDestructive

Request syntax

POST /rds/api/instances/{id}/restore
{
  "recoveryTarget": "enum",
  "targetIdentifier": "string",
  "instanceClass": "string",
  "topology": "enum",
  "kmsKeyId": "string",
  "publiclyAccessible": "boolean",
  "tags": "map of string",
  "recoveryTargetTime": "string",
  "recoveryTargetLabel": "string"
}

Path parameters

  • idRequired

    string

    Constraints: 3-64 chars, /^(?!ewdoc-)[a-z0-9-]+$/

Request body

The body takes one of several shapes (latest, time, label); the server decides which combination of fields is valid.

  • recoveryTargetRequired

    enum

    Selects which of the other fields apply

    One of: latest, time, label

  • targetIdentifierOptional

    string

    Name of the new database the restore creates; a restore never overwrites its source

    Constraints: 1-63 chars

  • instanceClassOptional

    string

    Instance type of the new database, e.g. performance-2 (provider names deprecated); omitted: the source's

    Constraints: min 1 chars

  • topologyOptional

    enum

    single (the default) or cluster: three nodes, the class needs 8 GiB of memory or more

    One of: single, cluster

  • kmsKeyIdOptional

    string

    KMS key for the new database's disks; null: the platform key; omitted: the source's

    Constraints: uuid

    May be null.

  • publiclyAccessibleOptional

    boolean

    Whether the new database answers on the internet; omitted: the source's choice

  • tagsOptional

    map of string

    Tags for the new resource, e.g. {"env": "prod", "project": "shop"}. Keys your organization marks required must be present, or the create is refused with the missing keys (GET /tags/api/keys lists them).

    Constraints: key=value

  • recoveryTargetTimeOptional

    string

    ISO time to restore to; must lie inside the recoverable window of backups list

    Constraints: datetime

  • recoveryTargetLabelOptional

    string

    Label of the backup to restore, as backups list shows it (e.g. 20260826-030000F)

    Constraints: 1-128 chars, /^[A-Za-z0-9_-]+$/

Response

202 with { job, target }: the restore job (status queued, as `list-restore-jobs` shows it) and the new database it builds, as `get` describes it without `placement`.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Fields of data

  • jobAlways

    object

    The restore job
  • job.​idAlways

    string

    Restore job id
  • job.​orgIdAlways

    string

    Organization that owns the databases
  • job.​sourceDbInstanceIdAlways

    string

    Database whose backups are restored
  • job.​targetDbInstanceIdAlways

    string, may be null

    New database the restore builds; null once that database is deleted
  • job.​recoveryTargetAlways

    one of latest, time, label

    latest, a point in time, or a labelled backup
  • job.​recoveryTargetTimeAlways

    string, may be null

    The point in time, for time
  • job.​recoveryTargetLabelAlways

    string, may be null

    The backup label, for label
  • job.​baseBackupLabelAlways

    string, may be null

    Backup the restore starts from; set when it starts
  • job.​statusAlways

    one of queued, restoring, completed, cancelled, failed

    cancelled: withdrawn before it started
  • job.​errorAlways

    string, may be null

    Why it failed or who cancelled it; null otherwise
  • job.​requestedByIamUserIdAlways

    string, may be null

    IAM user who asked; null once that user is deleted
  • job.​startedAtAlways

    string, may be null

    When the restore started
  • job.​finishedAtAlways

    string, may be null

    When it finished or was cancelled
  • job.​createdAtAlways

    string

    When it was requested
  • targetAlways

    object

    The new database the restore builds
  • target.​idAlways

    string

    Database id (ewdb-…)
  • target.​orgIdAlways

    string

    Organization that owns the database
  • target.​identifierAlways

    string

    Name of the database, unique within the organization
  • target.​engineAlways

    one of postgres, docdb

    Database engine; postgres for every managed PostgreSQL database
  • target.​engineVersionAlways

    string

    PostgreSQL version the database is on, a pinned minor such as 17.11
  • target.​instanceClassAlways

    string

    Instance type of every node, e.g. performance-2
  • target.​regionIdAlways

    string

    Region the database is in, e.g. de1
  • target.​availabilityZoneIdAlways

    string, may be null

    Zone asked for at create (e.g. de1b); null: the region's default zone, or spread over the zones for a cluster
  • target.​vpcIdAlways

    string, may be null

    VPC the database joins; null: none
  • target.​subnetIdAlways

    string, may be null

    Subnet of that VPC its addresses come from; null: the VPC's whole range
  • target.​dbNameAlways

    string, may be null

    Database created inside the server at launch
  • target.​masterUsernameAlways

    string

    Name of the master role, whose password is filed in Secrets
  • target.​allocatedStorageGibAlways

    number

    Size of each node's data volume, GiB
  • target.​maxAllocatedStorageGibAlways

    number, may be null

    Autoscaling ceiling, GiB; null: automatic growth is off
  • target.​storageTypeAlways

    string

    Storage class label; informational
  • target.​iopsAlways

    number, may be null

    Provisioned IOPS; not offered, so null
  • target.​multiAzAlways

    boolean

    Not used: zonePlacement says how a cluster is spread over zones
  • target.​publiclyAccessibleAlways

    boolean

    Whether the database answers on the internet; false: only from its VPC
  • target.​topologyAlways

    one of single, cluster

    single: one node; cluster: three nodes with automatic failover
  • target.​nodeCountAlways

    number

    Core nodes: 1 for single, 3 for a cluster (readers not counted)
  • target.​masterSecretIdAlways

    string, may be null

    Secret holding the master password; null until it is filed
  • target.​loadBalancerIdAlways

    string, may be null

    Load balancer in front of a cluster, on the platform's own fleet; null otherwise
  • target.​endpointKindAlways

    one of hetzner-lb, fleet, may be null

    What a cluster's endpoint is: fleet (the platform's own load balancer) or hetzner-lb (the provider's); null on a single node
  • target.​hetznerLoadBalancerIdAlways

    number, may be null

    The provider's id of a cluster's load balancer; null when there is none
  • target.​hetznerNetworkIdAlways

    number, may be null

    The provider's id of the private network a cluster's members talk over; null on a single node
  • target.​hetznerFirewallIdAlways

    number, may be null

    The provider's id of the database's firewall; null before it exists
  • target.​reconcileErrorAlways

    string, may be null

    Why the last provisioning or teardown step failed; null when nothing failed
  • target.​capacityFallbackAlways

    object

    What the create could fall back to when its type was sold out
  • target.​capacityFallback.​otherZonesAlways

    boolean

    A sold-out zone may be replaced by another zone of the region
  • target.​capacityFallback.​equivalentTypesAlways

    boolean

    A sold-out instance type may be replaced by an equivalent one
  • target.​onStockOutAlways

    one of fail, wait

    Sold out with no fallback: fail the create, or wait for stock
  • target.​capacityWaitUntilAlways

    string, may be null

    While waiting for stock: when the create gives up; null otherwise
  • target.​requestedInstanceClassAlways

    string, may be null

    The instance type asked for, when a stock fallback bought another; null otherwise
  • target.​statusAlways

    one of available, creating, modifying, backing-up, deleting, failed, stopped, starting, stopping, rebooting, maintenance, waiting-for-capacity, retained

    State of the database
  • target.​retainedUntilAlways

    string, may be null

    For a retained database: when its backups are removed; null otherwise
  • target.​endpointAddressAlways

    string, may be null

    Address clients connect to; null until the database is reachable
  • target.​endpointPortAlways

    number, may be null

    Direct PostgreSQL port of the endpoint (5432); the pooler is on 6432
  • target.​privateEndpointAddressAlways

    string, may be null

    The database's address inside its VPC, named in its certificate; null: use endpointAddress
  • target.​parameterGroupIdAlways

    string, may be null

    Not used; parameters holds your values
  • target.​backupRetentionDaysAlways

    number

    Days backups are kept; 0: scheduled backups are off
  • target.​backupsEnabledAlways

    boolean

    Whether scheduled backups are taken
  • target.​storageEncryptedAlways

    boolean

    Whether every node's data volume is encrypted at rest
  • target.​storageKmsKeyIdAlways

    string, may be null

    KMS key that wraps every node volume's key; null: the platform key
  • target.​backupAgentSeenAtAlways

    string, may be null

    When a node last asked for backup work; null: never
  • target.​backupPollerVersionAlways

    number, may be null

    Version of the backup service on the nodes; 3 and up keep a backup taken by hand until it is deleted; null: not reported
  • target.​lastBackupAtAlways

    string, may be null

    When the newest backup finished; null: never
  • target.​backupWindowAlways

    string, may be null

    When the daily backup runs, UTC HH:MM-HH:MM (only the start is used)
  • target.​maintenanceWindowAlways

    string, may be null

    Maintenance window, UTC ddd:hh24:mi-ddd:hh24:mi
  • target.​deletionProtectionAlways

    boolean

    While true, delete is refused
  • target.​performanceInsightsEnabledAlways

    boolean

    Not used; query insights are always on
  • target.​autoMinorVersionUpgradeAlways

    boolean

    Whether new minor versions are applied in the maintenance window
  • target.​parametersAlways

    map

    Your PostgreSQL parameter values by name; parameters not named keep their default
  • target.​caCertIdentifierAlways

    string, may be null

    Name of the CA that signs the server certificate
  • target.​tlsSerialAlways

    string, may be null

    Serial of the server certificate; null: the database has no certificate
  • target.​tlsNotAfterAlways

    string, may be null

    When the server certificate expires
  • target.​tlsNamesInCertAlways

    boolean

    Whether the certificate names the database's DNS endpoint names
  • target.​tlsRequiredAlways

    boolean

    Whether clients that do not use TLS are refused
  • target.​replicationModeAlways

    one of async, sync, may be null

    sync: a commit waits for one standby; async: it does not; null on a single node
  • target.​zonePlacementAlways

    one of spread, single, may be null

    spread: members over the zones; single: all in one zone; null on a single node
  • target.​logicalReplicationAlways

    boolean

    Whether wal_level is logical, for CDC and publications
  • target.​branchPoolOfAlways

    string, may be null

    Set on the machine that serves the branches of another database: that database; null otherwise
  • target.​branchSettingsAlways

    unknown

    Branch settings as stored (branch-settings reads them); null: the defaults
  • target.​launchedAtAlways

    string, may be null

    When the database first became available
  • target.​tagsAlways

    string, may be null

    Kept for compatibility; the tags API holds the tags of the database
  • target.​createdAtAlways

    string

    When the database was created
  • target.​updatedAtAlways

    string

    When the database record last changed
  • target.​encryptionAlways

    object

    What is encrypted at rest
  • target.​encryption.​storageAlways

    one of luks2, none

    luks2: every node's data volume is encrypted with a per-volume key from KMS; none: created before disk encryption
  • target.​encryption.​backupsAlways

    one of aes-256-cbc, none

    aes-256-cbc: backups are encrypted on the database machine before upload; none: created before backup encryption

Checked against the handlers: every route test validates their answers against this schema.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow rds:RestoreDBInstance on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud rds backups restore id --recovery-target latest

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_rds_backups_restore.