List Database Backups
A backup belongs to the database, not to an app: a gzipped SQL dump of the whole database, taken on demand or by its backup schedule. This lists one page of the database's backups, newest first, with what the caller can do with them, the schedule, the connected apps and what a restore would do. A database created under Storage → Databases has backups like any other, whether or not an app uses it. See Database backups for the dashboard side (the database's Backups tab).
Requires Databases read and a plan with managed databases. Taking, restoring and scheduling backups are gated by the same plan entitlements as app backups: application_db_backup (back up), application_db_restore (restore), application_backup_schedule (turn a schedule on) and backup_retention_max (how many a schedule keeps). Every backup route is also on the agent plane under /v1/agent/databases/{uuid}/backups and /v1/agent/databases/{uuid}/backup-schedule, for account-scoped agent tokens. A database or backup of another account answers 404.
Query parameters
1.100. Default 25; when you send page without page_size, the API's default page size (15).Response (200 OK)
{uuid, name, status, quota_paused, bundled_application_uuid}. bundled_application_uuid is the WordPress site that owns the database, or null.true when the plan grants neither a database backup nor a restore.bool): backup (the plan grants application_db_backup and the database is ready), restore (the plan grants application_db_restore, the database is ready and not paused), schedule (the plan grants application_db_backup and application_backup_schedule), download (the caller's role has Database data read).backup_retention_max: the most backups a schedule keeps. 0 when the plan sets none.pending or running.null when it has none.{application_uuid, application_name}, with legacy: true for an app bound to the database the older way, with no connection.warning).Backup object
{backup_uuid} of get, download, restore and delete.database.manual (on demand) or scheduled.pending → running → completed, or failed; deleting once a delete was requested.none, restoring, restored or failed: the last restore of this backup..sql.gz file; 0 until it has completed.Errors
Insufficient permissions for this action (no Databases read), No active account for this request, or Managed databases are not available on your plan.database not found.database_backups_unavailable: every database backup route answers this until the feature's database migration is applied (it is applied on ngris); databases_unavailable likewise for the Databases API.Back Up a Database
Take a backup now (the dashboard's Back up now). The backup is created pending; ngris then dumps the whole database (its tables, data and views) to a gzipped SQL file and it turns completed. Poll Get or the list for the status. No body is needed. One backup of a database runs at a time.
The database must be ready. A database paused over the plan's database limit can still be backed up: a backup only reads the data, and it is how you take the data out before deleting it. Requires Databases write and the plan's application_db_backup.
Response (201 Created)
{"backup": {…}}: the new backup object, status: "pending", trigger_source: "manual".
Errors
Database backup is not available on your plan., no Databases write, no active account, or no managed databases on the plan.database not found.backup_in_progress: A backup of this database is already in progress.database_status: the database isn't ready (e.g. Not possible while the database is provisioning.); resource and status say which.
database_backups_unavailable or databases_unavailable.Get a Database Backup
One backup of the database, in any status. Requires Databases read.
Response (200 OK)
{"backup": {…}} (backup object).
Errors
database not found or backup not found.database_backups_unavailable or databases_unavailable.Download a Database Backup
Stream a completed backup: the gzipped SQL dump, Content-Type: application/gzip, as an attachment named <database name>-<backup uuid>.sql.gz (characters other than letters, digits, ., _ and - in the name become -). The dump has no DROP TABLE statements: import it into an empty database.
The dump is the database's data, so this needs the role's Database data read permission (not Databases read). The account owner and the built-in Admin role have it; a custom role has it when its Database data row allows read (custom roles that existed before databases got their own permissions have it off). The list's capabilities.download says whether the caller has it. Every download is recorded in the account audit log.
Errors
Insufficient permissions for this action (no Database data read), no active account, or no managed databases on the plan.database not found, backup not found, or backup artifact not found (the stored file is gone).Only a completed backup can be downloaded.failed to read backup artifact: the storage couldn't be read; retry.Backup storage is not configured., database_backups_unavailable or databases_unavailable.Restore a Database Backup
Restore a completed backup into its database. The call is accepted asynchronously (202): the backup's restore_status goes restoring → restored, or failed with restore_error. ngris first drops every table and view in the database, then imports the dump, so until the import finishes connected apps can find tables missing. A restored view gets ngris's own internal user for this database as its definer (with the same rights as a read-write user on it), so it works as before. No body is needed; the dashboard asks you to type the database's name first.
One restore into a database runs at a time. Refused while the database is paused over the plan's database limit (it is read-only then) or isn't ready. Requires Databases update and the plan's application_db_restore.
Response (202 Accepted)
restoring.restore_status: "restoring".… It affects every application connected to it (orders-api): they keep running and see the restored data at once. With no app: … No application is connected to it.{application_uuid, application_name, legacy?}.Errors
Database restore is not available on your plan., no Databases update, no active account, or no managed databases on the plan.database not found or backup not found.quota_paused: the database is paused over your plan's database limit; it can't be restored until the account has room.database_status: the database isn't ready.restore_in_progress: A restore into this database is already in progress.backup_not_restorable: Only a completed backup can be restored.
database_backups_unavailable or databases_unavailable.Delete a Database Backup
Delete a completed or failed backup. It turns deleting and leaves the list; ngris then removes the stored file, then the record. This can't be undone. Allowed while the database is paused. Requires Databases delete.
You don't need to delete backups before deleting the database: deleting a database deletes all its backups.
Response (202 Accepted)
{"backup": {…}} with status: "deleting".
Errors
database not found or backup not found.backup_not_deletable: A backup can be deleted once it has completed or failed. (it is still pending or running, or already deleting).database_backups_unavailable or databases_unavailable.Audit trail
Every backup request, download, restore request, delete request and schedule change is recorded in the account audit log with event_type database: Database backup requested: <name>, Database backup downloaded: <name>, Database restore requested: <name>, Database backup deletion requested: <name> and Database backup schedule set: <name> (…).