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.
You can configure the following in Standard and Advanced clusters:
- The frequency of the backups to meet recovery point objective (RPO) requirements.
- The retention of the backups to set how long Cockroach Labs retains the backups.
Basic clusters have a default non-configurable schedule.
In addition to managed backups, you can take manual backups to your own storage bucket with self-managed backups. Refer to the Take and Restore Self-Managed Backups page.
Managed backup settings
You can modify the settings of managed backups in Standard and Advanced clusters.
Basic clusters have default settings that you cannot modify.
Basic clusters
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.
Refer to the Cloud Console section for details on viewing and managing the backups.
Standard and Advanced clusters
Configurable managed backup settings are available in all supported versions of CockroachDB on Standard and Advanced clusters.
In Standard and Advanced clusters, you can configure the frequency and retention of managed backups.
Standard and Advanced clusters take a combination of full and incremental backups in order to meet the set frequency. The type of managed backup the cluster takes is not configurable. Each incremental backup is dependent on the last full backup, which has an effect on the managed backups that you can restore in the set retention period.
Full backups in the cluster will be deleted when they reach the set retention period. At this point, any incremental backups dependent on the deleted full backup will also be deleted. The Cloud Console will not list any backups that are beyond the set retention period, or incremental backups that cannot be restored.
For instructions on how to view and configure managed backup settings, use:
Following a change to the backup frequency or retention setting, the cluster will take a full backup immediately, which may impact CPU usage on the cluster. If you are disabling managed backups, the cluster will not take a backup following the change.
Frequency
You can configure how frequently Cockroach Labs takes backups, which will determine the cluster's RPO.
You can set backup frequency to one of the following options:
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour (default)
- 4 hours
- 24 hours
Retention
You can set your retention duration once. After you have adjusted the retention, the duration will only apply to new backups. The available retention options are:
- 2 days
- 7 days
- 30 days (default)
- 90 days
- 365 days
You'll be able to modify the retention setting once for a cluster. To modify the setting again, contact the Cockroach Labs Support team.
When a cluster is deleted, Cockroach Labs will retain the managed backups for for the configured retention time, after which the backups will be deleted.
If a customer’s agreement with Cockroach Labs has terminated, all managed backups will be retained for a maximum of 30 days and then deleted. If a backup's retention time was set to less than 30 days, Cockroach Labs will retain the managed backups for the configured retention time, after which the backups will be deleted.
To restore a backup from a deleted cluster, you must contact the Cockroach Labs Support team.
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.
- You can perform a cross-cluster restore across Advanced clusters that belong to the same organization. However, this cross-cluster restore is not supported for Standard and Basic clusters.
- You cannot restore a backup of a multi-region database into a single-region database.
- For details on managed backups and enabling CMEK in Advanced clusters, refer to Backup and restore operations on a cluster with CMEK.
Cloud Console
Select the cluster tier to view its Cloud Console functionality:
View backups in a Basic cluster
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 ProgressorComplete. - 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 Basic cluster
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) as a golden rule when designing your system of privilege grants.
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:
- Find the cluster backup on the Backup Recovery page.
Click Restore for the cluster you want to restore.
The Restore cluster module displays with backup details.
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.
Click Restore.
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 ProgressorComplete. - 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.
Modify backup settings
Following a change to the backup frequency or retention setting, the cluster will take a full backup immediately, which may impact CPU usage on the cluster. If you are disabling managed backups, the cluster will not take a backup following the change.
Before modifying cluster backup settings, review details on backup settings for Standard and Advanced clusters.
Click on Settings and the Backup Settings module will open.
The Enable backups switch allows you to enable or disable backups.
To modify the frequency of backups, click on the dropdown under Schedule backups every. This will display the following options to select:
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour (default)
- 4 hours
- 24 hours
To modify the retention of backups, click on Retain backups for. This will display the following options to select:
- 2 days
- 7 days
- 30 days (default)
- 90 days
- 365 days
You'll be able to modify the retention setting once for a cluster. To modify the setting again, contact the Cockroach Labs Support team.
Restore a cluster
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) as a golden rule when designing your system of privilege grants.
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:
- Find the cluster backup on the Backup Recovery page.
Click Restore for the cluster you want to restore.
The Restore cluster module displays with backup details.
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.
Click Restore.
Cloud API for Standard clusters
You can use the CockroachDB Cloud API to view and modify managed backup settings in Standard and Advanced clusters.
The service account associated with the secret key must have the Cluster Administrator role.
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.
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups/config \
--header 'Authorization: Bearer {secret_key}'
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 resemblef78b7feb-b6cf-4396-9d7f-494982d7d81e.{secret_key}is your API key. Refer to API Access for more details.
If the request was successful, the API will return details about the managed backup settings:
{
"enabled": true,
"retention_days": 30,
"frequency_minutes": 240
}
{enabled}shows whether managed backups are enabled or disabled.{frequency_minutes}is how often the managed backup will run in minutes.{retention_days}is the number of days Cockroach Labs will retain the managed backup in storage.
Modify backup settings on a cluster
Following a change to the backup frequency or retention setting, the cluster will take a full backup immediately, which may impact CPU usage on the cluster. If you are disabling managed backups, the cluster will not take a backup following the change.
Before modifying cluster backup settings, review details on backup settings for Standard and Advanced clusters.
To configure the frequency and retention of managed backups, send a PUT request to the /v1/clusters/{cluster_id}/backups/config endpoint.
curl --request PUT \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups/config \
--header 'Authorization: Bearer {secret_key}' \
--data '{"enabled": true, "frequency_minutes": 30, "retention_days": 2}'
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 resemblef78b7feb-b6cf-4396-9d7f-494982d7d81e.{enabled}controls whether managed backups are enabled or disabled. If you are disabling managed backups, you cannot set backup frequency or retention. Possible values are:true,false.{frequency_minutes}determines how often the managed backup will run in minutes. Possible values are:5,10,15,30,60,240,1440.{retention_days}sets the number of days Cockroach Labs will retain the managed backup in storage. You can changeretention_daysfor the cluster once (whether in the Cloud API or 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.{secret_key}is your API key. Refer to API Access for more details.
If the request was successful, the client will receive an empty HTTP 200 OK status response.
View backups in an Advanced cluster
Click on Backup and Restore in the Data section of the left-side navigation to access the Backup Recovery page.
The Backups tab displays a list of your full and incremental 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 ProgressorComplete. - Type: Whether the backup is a full or incremental backup.
- Expires In: The remaining number of days Cockroach Labs will retain the backup.
- Databases: The number of databases included in the backup.
- Restore: Restore a particular cluster backup, click Restore in the corresponding row.
Databases
To view the databases included in the backup, click the number in the Databases column on the Backups tab.
For each database in the backup, the following details display:
- The Name of the database.
- The number of Tables in the database. If a database does not contain tables, it will not display in the Databases view.
Restore: To restore a database, click Restore in the corresponding row.
To view the tables in the database, click the number in the Tables column.
Tables
To view the tables in a database, click the number in the Tables column on the Databases page for a particular backup.
For each table in the database, the Name of the table displays.
To restore a table, click Restore in the corresponding row.
Modify backup settings in an Advanced cluster
Following a change to the backup frequency or retention setting, the cluster will take a full backup immediately, which may impact CPU usage on the cluster. If you are disabling managed backups, the cluster will not take a backup following the change.
Before modifying cluster backup settings, review details on backup settings for Standard and Advanced clusters.
On the Backup and Restore page, click on Settings and the Backup Settings module will open.
The Enable backups switch allows you to enable or disable backups.
To modify the frequency of backups, click on the dropdown under Schedule backups every. This will display the option to select one of the following:
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour (default)
- 4 hours
- 24 hours
To modify the retention of backups, click on Retain backups for. This will display the following options to select:
- 2 days
- 7 days
- 30 days (default)
- 90 days
- 365 days
You'll be able to modify the retention setting once for a cluster. To modify the setting again, contact the Cockroach Labs Support team.
Incomplete Backups
To view any failed or pending backups, click the Incomplete Backups tab on the Backup and Restore page.
For each incomplete backup, the following details display:
- Started: The date and time the backup job began.
- Duration: The amount of time the backup job ran for.
- Status: The error code and message for failed backup jobs.
- Description: The SQL command corresponding to the failed or pending backup job.
Restore data in Advanced clusters
Users with the Org Administrator, Cluster Operator, or Cluster Administrator roles can perform the following from the Console:
Restore an Advanced cluster
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) as a golden rule when designing your system of privilege grants.
To restore a cluster:
- Find the cluster backup on the Backups tab.
Click Restore for the cluster you want to restore.
The Restore cluster module displays with backup details.
Select the cluster to restore to. You can restore to either the same cluster or a different Advanced cluster in the same organization. Incompatible versions cannot be selected. By default, the option shows the current cluster. The dropdown displays options to restore to a different cluster.
Select the Skip localities check box if you want to skip checking localities of a cluster before a restore when there are mismatched cluster regions between the backup's cluster and the destination cluster.
Click Continue.
Enter the name of the destination cluster.
Once you have reviewed the restore details, click Restore.
The Restore Jobs tab will show you the status of your restore and update when the restore job has been created successfully.
Restore a database
To restore a database:
- On the Backups tab, find the cluster backup containing the database you want to restore, and click the number in the corresponding Databases column.
In the Databases view, click Restore for the database you want to restore.
The Restore database module displays with backup details.
In the Restore to fields:
- Select the name of the destination cluster.
- Type the name of the destination database.
Select any of the Dependency options to skip. You can:
- Skip missing foreign keys, which will remove missing foreign key constraints (i.e., when the referenced table is not in the backup or is not being restored) before restoring.
- Skip missing sequences, which will ignore sequence dependencies (i.e., the
DEFAULTexpression that uses the sequence). - Skip missing views, which will skip restoring views that cannot be restored because their dependencies are not being restored at the same time.
- Skip localities check, which will skip checking localities of a cluster before a restore when there are mismatched cluster regions between the backup's cluster and the destination cluster.
Click Continue.
Once you have reviewed the restore details, click Restore.
When the restore job has been created successfully, you will be taken to the Restore Jobs tab, which will show you the status of your restore.
When the restore is complete, be sure to set any database-specific zone configurations and, if applicable, grant privileges.
Restore a table
To restore a table:
- Find the cluster backup containing the table you want to restore, and click the number in the corresponding Databases column.
In the Databases view, find the database containing the table you want to restore, and click the number in the corresponding Tables column.
The Tables view displays.
Click Restore for the table you want to restore.
The Restore table module displays with backup details.
In the Restore to fields:
- Select the name of the destination cluster.
- Type the name of the destination database. (Before restoring, ensure that you do not have an existing table with the same name.)
Note:If you enter the name of an existing database, the table will be restored into that existing database. To use the name of an existing database, first resolve any naming conflicts with existing tables by using
DROPorRENAMEon the table. If you enter a unique name in the Restore to field, a new database will be created.Select any of the Dependency options to skip. You can:
- Skip missing foreign keys, which will remove missing foreign key constraints (i.e., when the referenced table is not in the backup or is not being restored) before restoring.
- Skip missing sequences, which will ignore sequence dependencies (i.e., the
DEFAULTexpression that uses the sequence). - Skip missing views, which will skip restoring views that cannot be restored because their dependencies are not being restored at the same time.
Click Continue.
Once you have reviewed the restore details, click Restore.
When the restore job has been created successfully, you will be taken to the Restore Jobs tab, which will show you the status of your restore.
Restore Jobs
To view the status of your restore, click on the Restore Jobs tab from the cluster Backup and Restore page.
For each restore job, the tab will display:
- Source > Destination: The source cluster, database, or table to the destination cluster, database, or table.
- Restore type: Whether the job is a cluster, database, table restore.
- Backup taken on: The date the backup was originally taken.
- Status: The status of the restore job
Preparing,Running,Succeeded,Failed. - Restore start: The date the restore job was initiated.
- Restore end: The date the restore job ened (whether successful or unsuccessful).
- Job ID: The job ID of the restore job.
Cloud API for Advanced clusters
You can use the CockroachDB Cloud API to view and modify managed backup settings in Standard and Advanced clusters.
The service account associated with the secret key must have the Cluster Administrator role.
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.
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups/config \
--header 'Authorization: Bearer {secret_key}'
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 resemblef78b7feb-b6cf-4396-9d7f-494982d7d81e.{secret_key}is your API key. Refer to API Access for more details.
If the request was successful, the API will return details about the managed backup settings:
{
"enabled": true,
"retention_days": 30,
"frequency_minutes": 240
}
{enabled}shows whether managed backups are enabled or disabled.{frequency_minutes}is how often the managed backup will run in minutes.{retention_days}is the number of days Cockroach Labs will retain the managed backup in storage.
Modify backup settings on a cluster
Following a change to the backup frequency or retention setting, the cluster will take a full backup immediately, which may impact CPU usage on the cluster. If you are disabling managed backups, the cluster will not take a backup following the change.
Before modifying cluster backup settings, review details on backup settings for Standard and Advanced clusters.
To configure the frequency and retention of managed backups, send a PUT request to the /v1/clusters/{cluster_id}/backups/config endpoint.
curl --request PUT \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/backups/config \
--header 'Authorization: Bearer {secret_key}' \
--data '{"enabled": true, "frequency_minutes": 30, "retention_days": 2}'
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 resemblef78b7feb-b6cf-4396-9d7f-494982d7d81e.{enabled}controls whether managed backups are enabled or disabled. If you are disabling managed backups, you cannot set backup frequency or retention. Possible values are:true,false.{frequency_minutes}determines how often the managed backup will run in minutes. Possible values are:5,10,15,30,60,240,1440.{retention_days}sets the number of days Cockroach Labs will retain the managed backup in storage. You can changeretention_daysfor the cluster once (whether in the Cloud API or 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.{secret_key}is your API key. Refer to API Access for more details.
If the request was successful, the client will receive an empty HTTP 200 OK status response.
Was this helpful?
