Managed Backups in CockroachDB Basic Clusters

On this page

Managed backups are automated backups of CockroachDB Cloud clusters that are stored by Cockroach Labs in cloud storage. By default, Cockroach Labs takes and retains managed backups in all Cloud clusters. In Standard and Advanced clusters, you can adjust the default managed backup settings to meet your organization's disaster recovery requirements.

This page describes managed backups in Basic clusters, which have a default non-configurable schedule.

Cockroach Labs will take a managed backup every 24 hours. By default, managed backups will be retained for 30 days in Basic clusters.

When a Basic cluster is deleted, or the customer’s agreement with Cockroach Labs has terminated, managed backups taken on the cluster will be retained for 30 days, after which the backups will be deleted.

For details on viewing and managing the backups, refer to the Cloud Console section.

Upgrades and downgrades

If you have upgraded from a Basic cluster to a Standard cluster, the existing backup schedules will still apply, but you can then configure the frequency and retention of future managed backups in the Standard cluster.

If you have downgraded from a Standard cluster to a Basic cluster, existing managed backups will be retained for the configured retention duration. The default managed backups in Basic clusters will be taken every 24 hours and have a 30-day retention.

Considerations

• Every backup will be stored entirely in a single region, which is chosen at random from the list of cluster regions at the time of cluster creation. This region will be used indefinitely to store backups.

For details on the storage costs of managed backups, refer to the Understand CockroachDB Cloud Costs page.

Required permissions to restore managed backups

To restore a managed backup successfully in CockroachDB Cloud, you must have the appropriate permissions on both the source and destination clusters:

• You must have either the Cluster Admin or Cluster Operator role on the destination cluster, or at the organization level. Without one of these roles, the restore operation will fail.
• You must also have either the Cluster Admin or Cluster Operator role on the source cluster (the cluster from which the backup was taken), or at the organization level. If you do not have the required permissions on the source cluster, the restore will fail.

Cloud Console

View backups

Click on Backup and Restore in the Data section of the left-side navigation to access the Backup Recovery page.

This page displays a list of your cluster backups. Use the calendar drop-down to view all backups taken on a certain date.

For each backup, the following details display:

• Data From: The date and time the backup was taken.
• Status: The backup's status, In Progress or Complete.
• Expires In: The remaining number of days Cockroach Labs will retain the backup.
• Restore: Restore a particular cluster backup, click Restore in the corresponding row.

Restore a cluster

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.

To restore a cluster:

1. Find the cluster backup on the Backup Recovery page.

2. Click Restore for the cluster you want to restore.

   The Restore cluster module displays with backup details.

3. You can restore a backup to the same cluster.

   Note:

   If you need to restore data into a new or different cluster, use self-managed backups or contact support.

4. Click Restore.

Cloud API

You can use the CockroachDB Cloud API to view managed backups or restore clusters/databases/tables from a managed backup.

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:

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 receives a JSON response listing backups with their unique {id} and {as_of_time} creation timestamp:

{
  "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

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.

On Standard and Basic clusters, restore operations can only be performed into the same cluster where the managed backup is stored.

Restore a cluster

To restore a managed backup of a cluster, send a POST request to the /v1/clusters/{cluster_id}/restores endpoint of "type": "CLUSTER":

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 uses the most recent backup. To restore a specific backup, include the backup_id field and specify a backup ID from the managed backups list:

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"
}'

You can specify additional options for the restore operation in the restore_opts object. For more information, see the API endpoint documentation.

If the request is successful, the client receives a JSON response that describes the request operation:

{
  "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 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:

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 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:

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 from a specific backup rather than the most recently created managed backup, include the backup_id field specifying a backup ID:

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.

If the request is successful, the client receives a response containing JSON describing the request operation:

{
  "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 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:

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 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_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:

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 from a specific backup rather than the most recently created managed backup, include the backup_id field specifying a backup ID:

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.

If the request is successful, the client receives a response containing JSON describing the request operation:

{
  "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 where restore_id is the id from the JSON response:

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 receives a response containing JSON describing the status of the specified request operation:

{
  "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
}