From 810e574ebd0617a2381377df75498f4354674220 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 28 Jul 2025 15:17:36 -0400 Subject: [PATCH 1/9] Add documentation for new backup and restore cloud API endpoints --- ...et-put.md => cloud-api-backup-settings.md} | 6 - .../backups/cloud-api-backup-view.md | 39 +++ .../backups/cloud-api-managed-backup-intro.md | 9 + .../backups/cloud-api-restore-endpoint.md | 246 ++++++++++++++++++ src/current/cockroachcloud/cloud-api.md | 4 + .../managed-backups-advanced.md | 8 +- .../cockroachcloud/managed-backups-basic.md | 10 +- src/current/cockroachcloud/managed-backups.md | 6 +- 8 files changed, 319 insertions(+), 9 deletions(-) rename src/current/_includes/cockroachcloud/backups/{cloud-api-get-put.md => cloud-api-backup-settings.md} (88%) create mode 100644 src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md create mode 100644 src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md create mode 100644 src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-get-put.md b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md similarity index 88% rename from src/current/_includes/cockroachcloud/backups/cloud-api-get-put.md rename to src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md index 40decb95e59..be6f584ec6f 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-get-put.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md @@ -1,9 +1,3 @@ -You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view](#get-information-on-backup-settings) and [modify](#modify-backup-settings-on-a-cluster) managed backup settings. - -{{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}} - ### Get information on backup settings To retrieve information about a specific cluster, make a `GET` request to the `/v1/clusters/{cluster_id}/backups/config` endpoint. diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md new file mode 100644 index 00000000000..9c95b816e7c --- /dev/null +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md @@ -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 was successful, the client will receive a JSON response listing backups with their unique `{id}` and `{as_of_time}` creation timestamp: + +~~~ 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 +~~~ diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md new file mode 100644 index 00000000000..ed16bdcbccb --- /dev/null +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md @@ -0,0 +1,9 @@ +{% 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) and [restore clusters/databases/tables](#restore-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) or [modify managed backup settings](#modify-backup-settings-on-a-cluster), [view managed backups](#view-managed-backups), and [restore clusters/databases/tables](#restore-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}} \ No newline at end of file diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md new file mode 100644 index 00000000000..baaf36c2ae4 --- /dev/null +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -0,0 +1,246 @@ +### Restore a managed backup + +You can use the `/v1/clusters/{cluster_id}/restores` endpoint to restore the contents of a managed backup at the cluster, database, or table level. + +{% if page.name == "managed-backups-advanced.md" %} +On Advanced clusters, restore operations can be performed 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. +{% endif %} + +#### Restore a cluster + +{{site.data.alerts.callout_danger}} +The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. + +This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. +{{site.data.alerts.end}} + +To restore a managed backup of a cluster, 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 '{ + "type": "CLUSTER" +}' +~~~ + +By default the restore operation will use the most recent backup. To restore a specific 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": "CLUSTER" +}' +~~~ + +{% if page.name == "managed-backups-advanced.md" %} +To restore a cluster backup into a new cluster, first create the target cluster. Send the restore request to the target cluster ID, specifying the ID of the source cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{target_cluster_id}/restores' \ +--header "Authorization: Bearer {secret_key}" \ +--json '{ + "source_cluster_id": "{source_cluster_id}", + "type": "CLUSTER" +}' +~~~ +{% endif %} + +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 was successful, the client will receive 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": "CLUSTER", + "completion_percent": 0 +} +~~~ + +#### Restore a database + +To restore a managed backup of a database to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the name of the source database in `objects.database`: + +{% 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 '{ + "type": "DATABASE", + "objects": [ + { + "database": "tpcc" + } + ] +} +~~~ + +By default the database will be restored into the original database name from the cluster backup. To restore the database contents into a new database, include the field `restore_opts.new_db_name` with the new database name: + +{% 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 '{ + "type": "DATABASE", + "objects": [ + { + "database": "tpcc" + } + ], + "restore_opts": { + "new_db_name": "tpcc2" + } +} +~~~ + +To restore 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" + } + ], +} +~~~ + +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 was successful, the client will receive 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": 0 +} +~~~ + +#### Restore a table + +To restore a managed backup of a table to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the fully qualified name of the source database 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 '{ + "type": "TABLE", + "objects": [ + { + "database": "tpcc", + "schema": "public", + "table": "warehouse" + } + ] +} +~~~ + +By default the table will be restored into the original database name from the cluster backup. To restore the table into a different database, include the field `restore_opts.into_name` with the 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 '{ + "type": "TABLE", + "objects": [ + { + "database": "tpcc", + "schema": "public", + "table": "warehouse" + } + ], + "restore_opts": { + "into_db": "tpcc2" + } +} +~~~ + +To restore 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" + } + ] +} +~~~ + +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 was successful, the client will receive 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": 0 +} +~~~ + +### 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: + +{% 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 was successful, the client will receive 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": 100 +} +~~~ \ No newline at end of file diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index c41153076ec..49164894854 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -629,6 +629,10 @@ curl --request PATCH \ Where `{cluster_id}` is the ID of your cluster and `{secret_key}` is your API key. +## Managed backups and restores + +For information on using the Cloud API to handle [managed backups and restore operations]({% link cockroachcloud/backup-and-restore-overview.md %}), see the respective managed backup documentation for [Basic]({% link cockroachcloud/managed-backups-basic.md %}#cloud-api), [Standard]({% link cockroachcloud/managed-backups.md %}#cloud-api), and [Advanced]({% link cockroachcloud/managed-backups-advanced.md %}#cloud-api) plans. + ## Change a cluster's plan This section shows how to change a cluster's plan using the CockroachDB {{ site.data.products.cloud }} API. To use Terraform instead, refer to [Provision a cluster with Terraform]({% link cockroachcloud/provision-a-cluster-with-terraform.md %}#change-a-clusters-plan). diff --git a/src/current/cockroachcloud/managed-backups-advanced.md b/src/current/cockroachcloud/managed-backups-advanced.md index f82f98347fc..d5088d62ed0 100644 --- a/src/current/cockroachcloud/managed-backups-advanced.md +++ b/src/current/cockroachcloud/managed-backups-advanced.md @@ -246,7 +246,13 @@ For each restore job, the tab will display: ## Cloud API -{% include cockroachcloud/backups/cloud-api-get-put.md %} +{% include cockroachcloud/backups/cloud-api-managed-backup-intro.md %} + +{% include cockroachcloud/backups/cloud-api-backup-settings.md %} + +{% include cockroachcloud/backups/cloud-api-backup-view.md %} + +{% include cockroachcloud/backups/cloud-api-restore-endpoint.md %} ## CockroachDB Cloud Terraform provider diff --git a/src/current/cockroachcloud/managed-backups-basic.md b/src/current/cockroachcloud/managed-backups-basic.md index e7565859155..31aeb342171 100644 --- a/src/current/cockroachcloud/managed-backups-basic.md +++ b/src/current/cockroachcloud/managed-backups-basic.md @@ -74,4 +74,12 @@ To restore a cluster: If you need to restore data into a new or different cluster, use [self-managed backups]({% link cockroachcloud/take-and-restore-self-managed-backups.md %}) or [contact support]({% link {{site.current_cloud_version}}/support-resources.md %}). {{site.data.alerts.end}} -1. Click **Restore**. \ No newline at end of file +1. Click **Restore**. + +## Cloud API + +{% include cockroachcloud/backups/cloud-api-managed-backup-intro.md %} + +{% include cockroachcloud/backups/cloud-api-backup-view.md %} + +{% include cockroachcloud/backups/cloud-api-restore-endpoint.md %} \ No newline at end of file diff --git a/src/current/cockroachcloud/managed-backups.md b/src/current/cockroachcloud/managed-backups.md index c70e0561e20..10ca0ec2152 100644 --- a/src/current/cockroachcloud/managed-backups.md +++ b/src/current/cockroachcloud/managed-backups.md @@ -132,7 +132,11 @@ To restore a cluster: ## Cloud API -{% include cockroachcloud/backups/cloud-api-get-put.md %} +{% include cockroachcloud/backups/cloud-api-managed-backup-intro.md %} + +{% include cockroachcloud/backups/cloud-api-backup-settings.md %} + +{% include cockroachcloud/backups/cloud-api-restore-endpoint.md %} ## CockroachDB Cloud Terraform provider From 2bc11c741459e3470e157db0883e3b928096a431 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 28 Jul 2025 15:32:32 -0400 Subject: [PATCH 2/9] Add cross-cluster restore operation examples --- .../backups/cloud-api-restore-endpoint.md | 54 ++++++++++++++++--- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md index baaf36c2ae4..9a6f3031fc3 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -87,7 +87,7 @@ curl --request POST \ "database": "tpcc" } ] -} +}' ~~~ By default the database will be restored into the original database name from the cluster backup. To restore the database contents into a new database, include the field `restore_opts.new_db_name` with the new database name: @@ -107,7 +107,7 @@ curl --request POST \ "restore_opts": { "new_db_name": "tpcc2" } -} +}' ~~~ To restore a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: @@ -125,8 +125,28 @@ curl --request POST \ "database": "tpcc" } ], -} +}' +~~~ + +{% if page.name == "managed-backups-advanced.md" %} +To restore a database from a managed backup into a different cluster, send the restore request to the target cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{target_cluster_id}/restores' \ +--header "Authorization: Bearer {secret_key}" \ +--json '{ + "source_cluster_id": "{source_cluster_id}", + "type": "DATABASE", + "objects": [ + { + "database": "tpcc" + } + ], +}' ~~~ +{% endif %} 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). @@ -161,7 +181,7 @@ curl --request POST \ "table": "warehouse" } ] -} +}' ~~~ By default the table will be restored into the original database name from the cluster backup. To restore the table into a different database, include the field `restore_opts.into_name` with the database name. The following example restores the `tpcc.public.warehouse` table from the most recent managed backup into `tpcc2.public.warehouse` on the cluster: @@ -183,7 +203,7 @@ curl --request POST \ "restore_opts": { "into_db": "tpcc2" } -} +}' ~~~ To restore a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: @@ -203,8 +223,30 @@ curl --request POST \ "table": "warehouse" } ] -} +}' +~~~ + +{% if page.name == "managed-backups-advanced.md" %} +To restore a table from a managed backup into a different cluster, send the restore request to the target cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. + +{% include_cached copy-clipboard.html %} +~~~ shell +curl --request POST \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{target_cluster_id}/restores' \ +--header "Authorization: Bearer {secret_key}" \ +--json '{ + "source_cluster_id": "{source_cluster_id}", + "type": "TABLE", + "objects": [ + { + "database": "tpcc", + "schema": "public", + "table": "warehouse" + } + ] +}' ~~~ +{% endif %} 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). From ac82b7a1aa09364cb76d83b3cd0b807bff9866ee Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 28 Jul 2025 15:40:08 -0400 Subject: [PATCH 3/9] Add missing view backups snippet --- src/current/cockroachcloud/managed-backups.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/current/cockroachcloud/managed-backups.md b/src/current/cockroachcloud/managed-backups.md index 10ca0ec2152..64171b8e747 100644 --- a/src/current/cockroachcloud/managed-backups.md +++ b/src/current/cockroachcloud/managed-backups.md @@ -136,6 +136,8 @@ To restore a cluster: {% include cockroachcloud/backups/cloud-api-backup-settings.md %} +{% include cockroachcloud/backups/cloud-api-backup-view.md %} + {% include cockroachcloud/backups/cloud-api-restore-endpoint.md %} ## CockroachDB Cloud Terraform provider From 9664c47766e778c3e0a6a8068b9d8b27e4af8c57 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 28 Jul 2025 15:53:57 -0400 Subject: [PATCH 4/9] Slight rewording --- .../cockroachcloud/backups/cloud-api-managed-backup-intro.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md index ed16bdcbccb..ab497163108 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md @@ -1,7 +1,7 @@ {% 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) and [restore clusters/databases/tables](#restore-a-managed-backup) from a managed backup. +You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view managed backups](#view-managed-backups) or [restore clusters/databases/tables](#restore-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) or [modify managed backup settings](#modify-backup-settings-on-a-cluster), [view managed backups](#view-managed-backups), and [restore clusters/databases/tables](#restore-a-managed-backup) from a managed backup. +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-a-managed-backup) from a managed backup. {% endif %} {{site.data.alerts.callout_info}} From 9c82b16828305c4b15c6a1ad0b3739d020a1cc90 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 28 Jul 2025 16:20:15 -0400 Subject: [PATCH 5/9] Corrections --- .../backups/cloud-api-managed-backup-intro.md | 4 ++-- .../backups/cloud-api-restore-endpoint.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md index ab497163108..fe2486e3a7f 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md @@ -1,7 +1,7 @@ {% 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/databases/tables](#restore-a-managed-backup) from a managed backup. +You can use the [CockroachDB Cloud API]({% link cockroachcloud/cloud-api.md %}) to [view managed backups](#view-managed-backups) or [restore clusters/databases/tables](#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-a-managed-backup) from a managed backup. +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}} diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md index 9a6f3031fc3..9f0f4b42c5b 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -1,4 +1,4 @@ -### Restore a managed backup +### Restore from a managed backup You can use the `/v1/clusters/{cluster_id}/restores` endpoint to restore the contents of a managed backup at the cluster, database, or table level. @@ -11,7 +11,7 @@ On Standard and Basic clusters, restore operations can only be performed into th #### Restore a cluster {{site.data.alerts.callout_danger}} -The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. +The restore operation completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. {{site.data.alerts.end}} @@ -73,7 +73,7 @@ If the request was successful, the client will receive a response containing JSO #### Restore a database -To restore a managed backup of a database to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the name of the source database in `objects.database`: +To restore a database from a managed backup to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the name of the source database in `objects.database`: {% include_cached copy-clipboard.html %} ~~~ shell @@ -90,7 +90,7 @@ curl --request POST \ }' ~~~ -By default the database will be restored into the original database name from the cluster backup. To restore the database contents into a new database, include the field `restore_opts.new_db_name` with the new database name: +By default the database will be 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: {% include_cached copy-clipboard.html %} ~~~ shell @@ -110,7 +110,7 @@ curl --request POST \ }' ~~~ -To restore a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: +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 @@ -165,7 +165,7 @@ If the request was successful, the client will receive a response containing JSO #### Restore a table -To restore a managed backup of a table to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the fully qualified name of the source database in `objects`: +To restore a table from a managed backup to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "TABLE"`. Specify the fully qualified name of the source table in `objects`: {% include_cached copy-clipboard.html %} ~~~ shell @@ -184,7 +184,7 @@ curl --request POST \ }' ~~~ -By default the table will be restored into the original database name from the cluster backup. To restore the table into a different database, include the field `restore_opts.into_name` with the database name. The following example restores the `tpcc.public.warehouse` table from the most recent managed backup into `tpcc2.public.warehouse` on the cluster: +By default the table will be restored into the original database name from the managed backup. To restore the table into a different database, include the field `restore_opts.into_name` 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 @@ -206,7 +206,7 @@ curl --request POST \ }' ~~~ -To restore a specific backup rather than the most recently created managed backup, include the `backup_id` field specifying a backup ID: +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 From 0b0a3203a2a422b2ee5ceb13ade6fcbb17740e74 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Wed, 30 Jul 2025 22:11:52 -0400 Subject: [PATCH 6/9] Address eng and PM comments --- .../backups/cloud-api-backup-settings.md | 6 +- .../backups/cloud-api-backup-view.md | 2 +- .../backups/cloud-api-managed-backup-intro.md | 4 +- .../backups/cloud-api-restore-endpoint.md | 82 +++++++++++-------- 4 files changed, 55 insertions(+), 39 deletions(-) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md index be6f584ec6f..6d749af5f33 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-settings.md @@ -14,7 +14,7 @@ Set the following: - `{cluster_id}` is the unique ID of the cluster. Use this ID when making API requests. You can find the cluster ID in the cluster's Cloud Console page. Find your cluster ID in the URL of the single cluster overview page: `https://cockroachlabs.cloud/cluster/{your_cluster_id}/overview`. The ID should resemble `f78b7feb-b6cf-4396-9d7f-494982d7d81e`. - `{secret_key}` is your API key. Refer to [API Access]({% link cockroachcloud/managing-access.md %}#api-access) for more details. -If the request was successful, the API will return details about the managed backup settings: +If the request is successful, the API will return details about the managed backup settings: ~~~json { @@ -53,7 +53,7 @@ Set the following: - `{frequency_minutes}` determines [how often](#frequency) the managed backup will run in minutes. Possible values are: `5`, `10`, `15`, `30`, `60`, `240` (4 hours), `1440` (24 hours). - `{retention_days}` sets the number of days Cockroach Labs will [retain](#retention) the managed backup in storage. You can change `retention_days` for the cluster **once** (whether in the Cloud API or [Cloud Console](#cloud-console)). Possible values are: `2`, `7`, `30`, `90`, `365`. - If `{retention_days}` has previously been modified (in the Cloud API or Cloud Console), you will receive the message "cluster already has a retention policy set, open a support ticket to change it". To modify the setting again, contact the [Cockroach Labs Support team]({% link {{site.current_cloud_version}}/support-resources.md %}). + If `{retention_days}` has previously been modified (in the Cloud API or Cloud Console), you receive the message "cluster already has a retention policy set, open a support ticket to change it". To modify the setting again, contact the [Cockroach Labs Support team]({% link {{site.current_cloud_version}}/support-resources.md %}). - `{secret_key}` is your API key. Refer to [API Access]({% link cockroachcloud/managing-access.md %}#api-access) for more details. -If the request was successful, the client will receive an empty HTTP 200 OK status response. \ No newline at end of file +If the request is successful, the client recieves an empty HTTP 200 OK status response. \ No newline at end of file diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md index 9c95b816e7c..11cd5b901ef 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md @@ -9,7 +9,7 @@ curl --request GET \ --header 'Authorization: Bearer {secret_key}' \ ~~~ -If the request was successful, the client will receive a JSON response listing backups with their unique `{id}` and `{as_of_time}` creation timestamp: +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 { diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md index fe2486e3a7f..68a16524a0b 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-managed-backup-intro.md @@ -1,5 +1,7 @@ {% 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/databases/tables](#restore-from-a-managed-backup) from a managed backup. +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 %} diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md index 9f0f4b42c5b..f81175d8d9c 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -1,22 +1,20 @@ ### Restore from a managed backup -You can use the `/v1/clusters/{cluster_id}/restores` endpoint to restore the contents of a managed backup at the cluster, database, or table level. +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 into the same cluster or a different Advanced cluster in the same organization. +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. +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_danger}} -The restore operation completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. - -This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. +{{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 managed backup of a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "CLUSTER"`: +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 @@ -24,11 +22,12 @@ 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 will use the most recent backup. To restore a specific backup, include the `backup_id` field specifying a backup ID: +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 @@ -42,12 +41,12 @@ curl --request POST \ ~~~ {% if page.name == "managed-backups-advanced.md" %} -To restore a cluster backup into a new cluster, first create the target cluster. Send the restore request to the target cluster ID, specifying the ID of the source cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. +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/{target_cluster_id}/restores' \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ --header "Authorization: Bearer {secret_key}" \ --json '{ "source_cluster_id": "{source_cluster_id}", @@ -56,9 +55,9 @@ curl --request POST \ ~~~ {% endif %} -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). +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). -If the request was successful, the client will receive a response containing JSON describing the request operation: +If the request is successful, the client recieves a JSON response that describes the request operation: ~~~ json { @@ -67,13 +66,14 @@ If the request was successful, the client will receive a response containing JSO "status": "PENDING", "created_at": "2025-07-25T16:45:14.064208710Z", "type": "CLUSTER", - "completion_percent": 0 + "completion_percent": 1 } ~~~ +{% if page.name == "managed-backups-advanced.md" %} #### Restore a database -To restore a database from a managed backup to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "DATABASE"`. Specify the name of the source database in `objects.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 @@ -81,16 +81,20 @@ 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 will be 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: +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 @@ -98,6 +102,7 @@ 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": [ { @@ -128,13 +133,12 @@ curl --request POST \ }' ~~~ -{% if page.name == "managed-backups-advanced.md" %} -To restore a database from a managed backup into a different cluster, send the restore request to the target cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. +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/{target_cluster_id}/restores' \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ --header "Authorization: Bearer {secret_key}" \ --json '{ "source_cluster_id": "{source_cluster_id}", @@ -146,11 +150,10 @@ curl --request POST \ ], }' ~~~ -{% endif %} 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 was successful, the client will receive a response containing JSON describing the request operation: +If the request is successful, the client recieves a response containing JSON describing the request operation: ~~~ json { @@ -159,13 +162,13 @@ If the request was successful, the client will receive a response containing JSO "status": "PENDING", "created_at": "2025-07-25T16:45:14.064208710Z", "type": "DATABASE", - "completion_percent": 0 + "completion_percent": 1 } ~~~ #### Restore a table -To restore a table from a managed backup to a cluster, send a `POST` request to the `/v1/clusters/{cluster_id}/restores` endpoint of `"type": "TABLE"`. Specify the fully qualified name of the source table in `objects`: +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 @@ -173,18 +176,24 @@ 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 will be restored into the original database name from the managed backup. To restore the table into a different database, include the field `restore_opts.into_name` 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: +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 @@ -192,12 +201,18 @@ 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": { @@ -226,13 +241,12 @@ curl --request POST \ }' ~~~ -{% if page.name == "managed-backups-advanced.md" %} -To restore a table from a managed backup into a different cluster, send the restore request to the target cluster ID. Specify the ID of the backup's cluster as `source_cluster_id`. Both the source cluster and the target cluster must use the Advanced plan. +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/{target_cluster_id}/restores' \ +--url 'https://cockroachlabs.cloud/api/v1/clusters/{destination_cluster_id}/restores' \ --header "Authorization: Bearer {secret_key}" \ --json '{ "source_cluster_id": "{source_cluster_id}", @@ -246,11 +260,10 @@ curl --request POST \ ] }' ~~~ -{% endif %} 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 was successful, the client will receive a response containing JSON describing the request operation: +If the request is successful, the client recieves a response containing JSON describing the request operation: ~~~ json { @@ -258,14 +271,15 @@ If the request was successful, the client will receive a response containing JSO "backup_id": "example-2d25-4a64-8172-28af7a0d41cc", "status": "PENDING", "created_at": "2025-07-25T16:45:14.064208710Z", - "type": "table", - "completion_percent": 0 + "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: +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 @@ -274,7 +288,7 @@ curl --request GET \ --header 'Authorization: Bearer {secret_key}' \ ~~~ -If the request was successful, the client will receive a response containing JSON describing the status of the specified request operation: +If the request is successful, the client recieves a response containing JSON describing the status of the specified request operation: ~~~ json { @@ -283,6 +297,6 @@ If the request was successful, the client will receive a response containing JSO "status": "SUCCESS", "created_at": "2025-07-25T16:45:14.064208710Z", "type": "CLUSTER", - "completion_percent": 100 + "completion_percent": 1 } ~~~ \ No newline at end of file From d1a7f1bc162356bb9bc306c18bc18150c71dd951 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 4 Aug 2025 11:56:15 -0400 Subject: [PATCH 7/9] Adjust restore_opt to be advanced only --- .../cockroachcloud/backups/cloud-api-restore-endpoint.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md index f81175d8d9c..1bfff5efd05 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -53,10 +53,11 @@ curl --request POST \ "type": "CLUSTER" }' ~~~ -{% endif %} 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). +{% endif %} + If the request is successful, the client recieves a JSON response that describes the request operation: ~~~ json From 7f7ea4b6fb2c5b8aaea86736877b56a04cbe4f10 Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 4 Aug 2025 11:57:37 -0400 Subject: [PATCH 8/9] Remove outdated cluster wipe warning --- src/current/cockroachcloud/managed-backups-advanced.md | 6 ++---- src/current/cockroachcloud/managed-backups-basic.md | 6 ++---- src/current/cockroachcloud/managed-backups.md | 6 ++---- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/src/current/cockroachcloud/managed-backups-advanced.md b/src/current/cockroachcloud/managed-backups-advanced.md index d5088d62ed0..82ab52c5f8c 100644 --- a/src/current/cockroachcloud/managed-backups-advanced.md +++ b/src/current/cockroachcloud/managed-backups-advanced.md @@ -144,10 +144,8 @@ Users with the [Organization Admin]({% link cockroachcloud/authorization.md %}#o #### Restore an Advanced cluster -{{site.data.alerts.callout_danger}} -The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. - -This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. +{{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: diff --git a/src/current/cockroachcloud/managed-backups-basic.md b/src/current/cockroachcloud/managed-backups-basic.md index 31aeb342171..9133ff2ffba 100644 --- a/src/current/cockroachcloud/managed-backups-basic.md +++ b/src/current/cockroachcloud/managed-backups-basic.md @@ -53,10 +53,8 @@ For each backup, the following details display: ### Restore a cluster -{{site.data.alerts.callout_danger}} -The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. - -This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. +{{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}} Performing a restore will cause your cluster to be unavailable for the duration of the restore. All current data is deleted, and the cluster will be restored to the state it was in at the time of the backup. diff --git a/src/current/cockroachcloud/managed-backups.md b/src/current/cockroachcloud/managed-backups.md index 64171b8e747..4a44c061b68 100644 --- a/src/current/cockroachcloud/managed-backups.md +++ b/src/current/cockroachcloud/managed-backups.md @@ -107,10 +107,8 @@ To modify the [retention](#retention) of backups, click on **Retain backups for* ### Restore a cluster -{{site.data.alerts.callout_danger}} -The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress. - -This operation is disruptive and is to be performed with caution. Use the [Principle of Least Privilege (PoLP)](https://wikipedia.org/wiki/Principle_of_least_privilege) as a golden rule when designing your system of privilege grants. +{{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}} Performing a restore will cause your cluster to be unavailable for the duration of the restore. All current data is deleted, and the cluster will be restored to the state it was in at the time of the backup. From e00165749353f59067d59393b7bc7e9427cca83c Mon Sep 17 00:00:00 2001 From: Joe Lodin Date: Mon, 11 Aug 2025 17:48:21 -0400 Subject: [PATCH 9/9] Add limited preview notes --- .../cockroachcloud/backups/cloud-api-backup-view.md | 4 ++++ .../cockroachcloud/backups/cloud-api-restore-endpoint.md | 8 ++++++++ src/current/cockroachcloud/cloud-api.md | 4 ++++ src/current/v25.3/cockroachdb-feature-availability.md | 3 +++ 4 files changed, 19 insertions(+) diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md index 11cd5b901ef..627a382ce49 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md @@ -1,5 +1,9 @@ ### View managed backups +{{site.data.alerts.callout_info}} +{% include feature-phases/limited-access.md %} +{{site.data.alerts.end}} + 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 %} diff --git a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md index 1bfff5efd05..9630725c745 100644 --- a/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md +++ b/src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md @@ -1,5 +1,9 @@ ### Restore from a managed backup +{{site.data.alerts.callout_info}} +{% include feature-phases/limited-access.md %} +{{site.data.alerts.end}} + 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" %} @@ -280,6 +284,10 @@ If the request is successful, the client recieves a response containing JSON des ### Get status of a restore operation +{{site.data.alerts.callout_info}} +{% include feature-phases/limited-access.md %} +{{site.data.alerts.end}} + 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 %} diff --git a/src/current/cockroachcloud/cloud-api.md b/src/current/cockroachcloud/cloud-api.md index 49164894854..831c19d8990 100644 --- a/src/current/cockroachcloud/cloud-api.md +++ b/src/current/cockroachcloud/cloud-api.md @@ -631,6 +631,10 @@ Where `{cluster_id}` is the ID of your cluster and `{secret_key}` is your API ke ## Managed backups and restores +{{site.data.alerts.callout_info}} +{% include feature-phases/limited-access.md %} +{{site.data.alerts.end}} + For information on using the Cloud API to handle [managed backups and restore operations]({% link cockroachcloud/backup-and-restore-overview.md %}), see the respective managed backup documentation for [Basic]({% link cockroachcloud/managed-backups-basic.md %}#cloud-api), [Standard]({% link cockroachcloud/managed-backups.md %}#cloud-api), and [Advanced]({% link cockroachcloud/managed-backups-advanced.md %}#cloud-api) plans. ## Change a cluster's plan diff --git a/src/current/v25.3/cockroachdb-feature-availability.md b/src/current/v25.3/cockroachdb-feature-availability.md index b3794965ee0..7bcbcc2d92d 100644 --- a/src/current/v25.3/cockroachdb-feature-availability.md +++ b/src/current/v25.3/cockroachdb-feature-availability.md @@ -37,6 +37,9 @@ Any feature made available in a phase prior to GA is provided without any warran ### Export metrics to Azure Monitor [Exporting Metrics to Azure Monitor]({% link cockroachcloud/export-metrics-advanced.md %}?filters=azure-monitor-metrics-export) from a CockroachDB {{ site.data.products.advanced }} cluster hosted on Azure is in limited access. Once the export is configured, metrics will flow from all nodes in all regions of your CockroachDB {{ site.data.products.advanced }} cluster to your chosen cloud metrics sink. To express interest and try it out, contact [Support](https://support.cockroachlabs.com/hc). +### Backup and restore with the Cloud API +You can use the [Cloud API]({% link cockroachcloud/cloud-api.md %}#managed-backups-and-restores) to handle [managed backups and restore operations]({% link cockroachcloud/backup-and-restore-overview.md %}). To express interest and try out these API endpoints, contact [Support](https://support.cockroachlabs.com/hc). + ### Cluster SSO backed by LDAP [Cluster SSO]({% link {{ page.version.version }}/sso-sql.md %}) using an identity stored in LDAP is in Limited Access. The [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `server.auth_log.sql_sessions.enabled`, which logs more details about cluster authentication failures, is also in Limited Access.