Add documentation for new backup and restore cloud API endpoints #20012
Conversation
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
Would you be able to fix the first link for "Managed backups" in the following section? https://deploy-preview-20012--cockroachdb-docs.netlify.app/docs/cockroachcloud/backup-and-restore-overview#managed-backups
It currently points to the same page. Please make it point to https://deploy-preview-20012--cockroachdb-docs.netlify.app/docs/cockroachcloud/managed-backups
I just realized that it is in an include file as the intro paragraph for the managed-backup pages.
lgtm pending suggestions (mostly nits about verb tense)
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md
Outdated
Show resolved
Hide resolved
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "CLUSTER", | ||
| "completion_percent": 0 |
There was a problem hiding this comment.
nit - can we say 100 as that would be 100% completed aka successful?
There was a problem hiding this comment.
@linhcrl I believe on Intrusion we return a float64 (i.e. 1 instead of 100). Does Console update this to a percentage value?
There was a problem hiding this comment.
nope, we keep it a float between 0 and 1
There was a problem hiding this comment.
This should be call fraction_completed
There was a problem hiding this comment.
we purposely renamed it for the CC API
There was a problem hiding this comment.
This should be read as the JSON returned immediately to the POST request, wouldn't it show the lowest completion percent?
| @@ -0,0 +1,288 @@ | |||
| ### 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. | |||
There was a problem hiding this comment.
can we change {cluster_id} to {target_cluster_id} to indicate that its the cluster that we intend to restore to? and change that on all subsequent fields where this is used?
There was a problem hiding this comment.
Just a small note - if I recall correctly, we agreed on using the destination_cluster_id terminology for backup/restore (instead of target_cluster_id)
There was a problem hiding this comment.
I'm having trouble reconciling this suggestion with the info that either backup_id or source_cluster_id must be included in a restore request. Because for any restore operations where the user just wants to restore the most recent backup and isn't restoring between clusters, the example would have them set:
..
--json '{
"source_cluster_id": "{destination_cluster_id}"
..
}'
Unless the use of {variable_name} needs to be specific and consistent for use with Terraform or somesuch, I would prefer to generically use {cluster_id} unless we're specifically talking about restores between clusters; I'll update all of those examples now.
There was a problem hiding this comment.
Sounds good, I just want to avoid confusion between source backup cluster and target restore cluster
| #### 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. |
There was a problem hiding this comment.
We need to update the docs here - we actually don't delete everything anymore. The restore will be blocked from initiating if a user has a table/database that exists in the cluster. @benbardin in a full cluster restore, its blocked if there are objects in the target cluster right?
There was a problem hiding this comment.
Yes, it is now the responsibility of the user to wipe all tables in their cluster.
- Not Ben Bardin
There was a problem hiding this comment.
Does that apply to non-API cluster restores too? I pulled this note from the console docs.
There was a problem hiding this comment.
Correct, we need to update Console docs as well
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
| #### 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. |
There was a problem hiding this comment.
Yes, it is now the responsibility of the user to wipe all tables in their cluster.
- Not Ben Bardin
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "CLUSTER", | ||
| "completion_percent": 0 |
There was a problem hiding this comment.
@linhcrl I believe on Intrusion we return a float64 (i.e. 1 instead of 100). Does Console update this to a percentage value?
src/current/_includes/cockroachcloud/backups/cloud-api-backup-view.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
| "status": "PENDING", | ||
| "created_at": "2025-07-25T16:45:14.064208710Z", | ||
| "type": "CLUSTER", | ||
| "completion_percent": 0 |
There was a problem hiding this comment.
nope, we keep it a float between 0 and 1
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Show resolved
Hide resolved
src/current/_includes/cockroachcloud/backups/cloud-api-restore-endpoint.md
Outdated
Show resolved
Hide resolved
| ~~~ | ||
| {% 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). |
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.
|
|
||
| #### 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`: |
There was a problem hiding this comment.
Should we mention that we can support multiple dbs and tables restore in the objects? Also, We need to call out that new_db_name only allow one db restore at a time. If we have multiple dbs and want to restore into different new_db_name. then it need to call restore api multiple time.
Example:
demo@127.0.0.1:26257/demoapp/testdb3> RESTORE DATABASE testdb1, testdb2 FROM LATEST IN 'nodelocal://1/cluster_backup'
-> WITH new_db_name = 'merged_database';
ERROR: new_db_name can only be used for RESTORE DATABASE with a single target databaseCC: @linhcrl
There was a problem hiding this comment.
Added. Can you restore more than one table at a time if you're specifying into_db? And can those source tables be in different databases or schemas?
There was a problem hiding this comment.
Yes, it can be restore tables from different databases (can be in different schemas as well) into the same destination database (will put them in the source table's schema).
Example:
demo@127.0.0.1:26257/hr_db> RESTORE TABLE sales_db.customers, sales_db.orders, inventory_db.products, hr_db.employees
-> FROM '/2025/08/01-163014.07' IN 'nodelocal://1/backup/'
-> WITH into_db = 'consolidated_db';
job_id | status | fraction_completed | rows
----------------------+-----------+--------------------+-------
1094436468599422977 | succeeded | 1 | 6
(1 row)
Time: 123ms total (execution 123ms / network 0ms)
demo@127.0.0.1:26257/hr_db> show tables from consolidated_db;
schema_name | table_name | type | owner | estimated_row_count | locality
--------------+------------+-------+-------+---------------------+-----------
public | customers | table | demo | 2 | NULL
public | employees | table | demo | 2 | NULL
public | orders | table | demo | 0 | NULL
public | products | table | demo | 2 | NULL
(4 rows)
Time: 31ms total (execution 30ms / network 1ms)
jhlodin
force-pushed
the
jl/doc-11599
branch
2 times, most recently
from
b39cf4d to
52ac555
Compare
Fixes DOC-11599
Add task-oriented guidance to our docs around using the cloud API to:
Opted to break out our existing include(s) for human readability due to different functionality between Cloud plans