Add documentation for new backup and restore cloud API endpoints #20012
+389
−24
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,39 @@ | ||
| ### View managed backups | ||
|
|
||
| To view a list of managed backups on a cluster with timestamps and their respective IDs, send a `GET` request to the `/v1/clusters/{cluster_id}/backups` endpoint: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request GET \ | ||
| --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups \ | ||
| --header 'Authorization: Bearer {secret_key}' \ | ||
| ~~~ | ||
|
|
||
| If the request is successful, the client recieves a JSON response listing backups with their unique `{id}`. The `{as_of_time}` timestamp describes the system time of the cluster when the backup was created: | ||
|
|
||
| ~~~ json | ||
| { | ||
| "backups": [ | ||
| { | ||
| "id": "example-157a-4b04-8f72-3179369a50d9", | ||
| "as_of_time": "2025-07-25T15:45:00Z" | ||
| }, | ||
| { | ||
| "id": "example-c090-429c-9f84-2b1297f5de89", | ||
| "as_of_time": "2025-07-25T15:35:32Z" | ||
| }, | ||
| { | ||
| "id": "example-4e41-44ec-926a-0cc368efdea2", | ||
| "as_of_time": "2025-07-25T15:00:00Z" | ||
| }, | ||
| { | ||
| "id": "example-3c67-4822-b7b9-90c2d8cc06a3", | ||
| "as_of_time": "2025-07-25T14:56:15Z" | ||
| }, | ||
| { | ||
| "id": "example-abef-4191-aa98-36a019da97c2", | ||
| "as_of_time": "2025-07-25T14:52:05.637170Z" | ||
| } | ||
| ], | ||
| "pagination": null | ||
| ~~~ |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| {% if page.name == "managed-backups-basic.md" %} | ||
| You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view managed backups](#view-managed-backups) or [restore clusters](#restore-from-a-managed-backup) from a managed backup. | ||
| {% else if page.name == "managed-backups.md" %} | ||
| You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view](#get-information-on-backup-settings) and [modify managed backup settings](#modify-backup-settings-on-a-cluster), [view managed backups](#view-managed-backups), or [restore clusters](#restore-from-a-managed-backup) from a managed backup. | ||
| {% else %} | ||
| You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view](#get-information-on-backup-settings) and [modify managed backup settings](#modify-backup-settings-on-a-cluster), [view managed backups](#view-managed-backups), or [restore clusters/databases/tables](#restore-from-a-managed-backup) from a managed backup. | ||
| {% endif %} | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| The [service account]({% link cockroachcloud/authorization.md %}#service-accounts) associated with the secret key must have the [Cluster Admin]({% link cockroachcloud/authorization.md %}#cluster-admin) role. | ||
| {{site.data.alerts.end}} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,303 @@ | ||
| ### Restore from a managed backup | ||
|
|
||
| You can use the `/v1/clusters/{destination_cluster_id}/restores` endpoint to restore the contents of a managed backup to a specified destination cluster. | ||
|
|
||
| {% if page.name == "managed-backups-advanced.md" %} | ||
| On Advanced clusters, restore operations can be performed at the cluster, database, or table level into the same cluster or a different Advanced cluster in the same organization. | ||
| {% else %} | ||
| On Standard and Basic clusters, restore operations can only be performed into the same cluster where the managed backup is stored. Managed backups can only be restored at the cluster level. | ||
| {% endif %} | ||
|
|
||
| #### Restore a cluster | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| Before a cluster can be restored from a managed backup, the destination cluster must be completely wiped of data. A cluster restore operation fails if the destination cluster contains any databases/schemas/tables. | ||
| {{site.data.alerts.end}} | ||
|
|
||
| To restore a cluster to a recent managed backup, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "CLUSTER"`: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{cluster_id}" | ||
| "type": "CLUSTER" | ||
| }' | ||
| ~~~ | ||
|
|
||
| By default, the restore operation uses the most recent backup stored within the last 7 days on the cluster specified in `source_cluster_id`. To restore a specific backup, include the `backup_id` field and specify a backup ID from the [managed backups list](#view-managed-backups): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "type": "CLUSTER" | ||
| }' | ||
| ~~~ | ||
|
|
||
| {% if page.name == "managed-backups-advanced.md" %} | ||
| To restore a cluster backup into a different cluster, ensure that the destination cluster is created and contains no databases/schemas/tables. Send the restore request to the destination cluster ID, specifying the ID of the source cluster as `source_cluster_id`. Both the source cluster and the destination cluster must use the Advanced plan. | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{source_cluster_id}", | ||
| "type": "CLUSTER" | ||
| }' | ||
| ~~~ | ||
|
|
||
| You can specify additional options for the restore operation in the `restore_opts` object. For more information, see the [API endpoint documentation](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/restores-config). | ||
|
There was a problem hiding this comment. I put this in as a placeholder for the actual API reference docs URL. If it'll be different when published, please let me know and I can update. There was a problem hiding this comment. Sounds good, please tag me when the param document is available. Thanks! There was a problem hiding this comment. It should be part of the proto? Since this link goes out to the API documentation, it's not going to docs that I'm writing. |
||
|
|
||
| {% endif %} | ||
|
|
||
| If the request is successful, the client recieves a JSON response that describes the request operation: | ||
|
|
||
| ~~~ json | ||
| { | ||
jhlodin marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "id": "example-aeb7-4daa-9e2c-eda541765f8a", | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "CLUSTER", | ||
| "completion_percent": 1 | ||
| } | ||
| ~~~ | ||
|
|
||
| {% if page.name == "managed-backups-advanced.md" %} | ||
| #### Restore a database | ||
|
|
||
| To restore one or more databases from a cluster's managed backup, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the name of the databases in `objects`: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{cluster_id}" | ||
| "type": "DATABASE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc" | ||
| }, | ||
| { | ||
| "database": "movr" | ||
| } | ||
| ] | ||
| }' | ||
| ~~~ | ||
|
|
||
| By default, the database is restored into the original database name from the managed backup. To restore the database contents into a new database, include the field `restore_opts.new_db_name` with the new database name. You can only restore one database at a time when using this option. | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{cluster_id}" | ||
| "type": "DATABASE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc" | ||
| } | ||
| ], | ||
| "restore_opts": { | ||
| "new_db_name": "tpcc2" | ||
| } | ||
| }' | ||
| ~~~ | ||
|
|
||
| To restore from a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "type": "DATABASE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc" | ||
| } | ||
| ], | ||
| }' | ||
| ~~~ | ||
|
|
||
| To restore a database from a source cluster's managed backup into a different cluster, send the restore request to the destination cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the destination cluster must use the Advanced plan. | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{source_cluster_id}", | ||
| "type": "DATABASE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc" | ||
| } | ||
| ], | ||
| }' | ||
| ~~~ | ||
|
|
||
| You can specify additional options for the restore operations in the `restore_opts` object. For more information, see the [API endpoint documentation](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/restores-config). | ||
|
|
||
| If the request is successful, the client recieves a response containing JSON describing the request operation: | ||
|
|
||
| ~~~ json | ||
| { | ||
| "id": "example-aeb7-4daa-9e2c-eda541765f8a", | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "DATABASE", | ||
| "completion_percent": 1 | ||
| } | ||
| ~~~ | ||
|
|
||
| #### Restore a table | ||
|
|
||
| To restore a one or more tables from a cluster's managed backup, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "TABLE"`. Specify the fully qualified name of the source tables in `objects`: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{cluster_id}" | ||
| "type": "TABLE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "warehouse" | ||
| }, | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "customer" | ||
| } | ||
| ] | ||
| }' | ||
| ~~~ | ||
|
|
||
| By default, the table is restored into the original database name from the managed backup. To restore the table into a different database, include the field `restore_opts.into_db` with the desired database name. The following example restores the `tpcc.public.warehouse` table from the most recent managed backup into `tpcc2.public.warehouse` on the cluster: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{cluster_id}" | ||
| "type": "TABLE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "warehouse" | ||
| }, | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "customer" | ||
| } | ||
| ], | ||
| "restore_opts": { | ||
| "into_db": "tpcc2" | ||
| } | ||
| }' | ||
| ~~~ | ||
|
|
||
| To restore from a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "type": "TABLE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "warehouse" | ||
| } | ||
| ] | ||
| }' | ||
| ~~~ | ||
|
|
||
| To restore a table from a source cluster's managed backup into a different cluster, send the restore request to the destination cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the destination cluster must use the Advanced plan. | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request POST \ | ||
| --url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ | ||
| --header "Authorization: Bearer {secret_key}" \ | ||
| --json '{ | ||
| "source_cluster_id": "{source_cluster_id}", | ||
| "type": "TABLE", | ||
| "objects": [ | ||
| { | ||
| "database": "tpcc", | ||
| "schema": "public", | ||
| "table": "warehouse" | ||
| } | ||
| ] | ||
| }' | ||
| ~~~ | ||
|
|
||
| You can specify additional options for the restore operations in the `restore_opts` object. For more information, see the [API endpoint documentation](https://www.cockroachlabs.com/docs/api/cloud/v1#get-/api/v1/clusters/-cluster_id-/restores-config). | ||
|
|
||
| If the request is successful, the client recieves a response containing JSON describing the request operation: | ||
|
|
||
| ~~~ json | ||
| { | ||
| "id": "example-aeb7-4daa-9e2c-eda541765f8a", | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "TABLE", | ||
| "completion_percent": 1 | ||
| } | ||
| ~~~ | ||
| {% endif %} | ||
|
|
||
| ### Get status of a restore operation | ||
|
|
||
| To view the status of a restore operation using the cloud API, send a `GET` request to the `/v1/clusters/{cluster_id}/restores/{restore_id}` endpoint where `restore_id` is the `id` from the JSON response: | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ shell | ||
| curl --request GET \ | ||
| --url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/restores/{restore_id} \ | ||
| --header 'Authorization: Bearer {secret_key}' \ | ||
| ~~~ | ||
|
|
||
| If the request is successful, the client recieves a response containing JSON describing the status of the specified request operation: | ||
|
|
||
| ~~~ json | ||
| { | ||
| "id": "example-aeb7-4daa-9e2c-eda541765f8a", | ||
| "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", | ||
| "status": "SUCCESS", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "CLUSTER", | ||
| "completion_percent": 1 | ||
| } | ||
| ~~~ | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.