Skip to main content
Restores a database with managed SQL roles in place from a verified DBHost backup of that same database. The restore replaces the current contents, so writes made after the backup are no longer present. The role usernames and passwords stay the same. For other database types, see Restore from a DBHost backup. Every database with managed roles can be restored, whether it has only its owner, runtime and read-only roles or also additional roles. The backup must list the same roles the database has now: after you add or remove an additional role, restore from a backup taken after that change. An older backup is refused when its roles no longer match: the restore operation then ends as failed with a message saying so, and the database is left unchanged. Start a new restore from a backup taken after the latest role change. Both endpoints require Pro or Business and a full-account API key. A key scoped to selected databases receives 403 KEY_SCOPE_DENIED; see Authentication. Every response, including errors, is sent with Cache-Control: no-store.

​
How it works

  1. Find a backup ID with GET /api/v1/databases/{id}/backups.
  2. Reserve the restore with POST /api/v1/databases/{id}/managed-restores. This returns an operation ID and does not change the database yet.
  3. Call POST /api/v1/operations/{operationId}/managed-restore/advance repeatedly until it returns 200 with status: "succeeded".
  4. Read progress at any time with GET /api/v1/operations/{operationId}.
Expect open connections to drop during the cutover; your application must reconnect. While the restore is in progress, role rotations and revocations, creating or removing additional roles, and extension changes are refused.

​
Reserve a restore

​
Path parameters

​
Headers

Generate the key once and keep it. If a request times out or the result is uncertain, send the same request with the same key to get the original operation back. Do not send a new key to retry; that would reserve a second restore. A key belongs to one restore across your account: using it with a different database or backup returns 409 MANAGED_ROLE_CONFLICT.

​
Body

The body must contain exactly one field: The backup must be a verified DBHost backup of this same database that includes its managed role manifest and is still within retention. You cannot restore one database’s backup into another database.

​
Response

202 Accepted
The status code is 202 until the operation has succeeded, then 200. If the key refers to a restore that failed or was canceled, the response is 409 RESTORE_OPERATION_TERMINAL; start a new restore with a new key. The reservation is refused with 409 MANAGED_ROLE_CONFLICT when the backup does not qualify, a role rotation or revocation on the database is unfinished, an additional role is still being created or removed, or another operation holds the database.

​
Advance the restore

Send no body. Each call moves the operation forward from its current state and returns it:
202 Accepted
Repeat the call for the same operation until it returns 200 with "status": "succeeded". Calling it again after success returns the same result. stage is informational and its values can change; rely on status. Do not reserve a second restore to retry a stage. DBHost verifies the backup and restores into an isolated copy before it switches over. If verification fails, the current database is left unchanged.

​
Errors

The reserve endpoint allows six requests per hour per API key, including retries. The dashboard and the CLI have no restore action for databases with managed SQL roles.