From 935ee0805eba1ee1101519c1d0dc54060e775686 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Thu, 30 Oct 2025 14:18:29 -0400 Subject: [PATCH 1/6] Restructured section Restructured backup and dr section for clarity and thoroughness --- .../v25.4/work-with-virtual-clusters.md | 49 +++++++++++++------ 1 file changed, 33 insertions(+), 16 deletions(-) diff --git a/src/current/v25.4/work-with-virtual-clusters.md b/src/current/v25.4/work-with-virtual-clusters.md index 6adfd10f847..edb0248915e 100644 --- a/src/current/v25.4/work-with-virtual-clusters.md +++ b/src/current/v25.4/work-with-virtual-clusters.md @@ -118,21 +118,45 @@ When connected to a virtual cluster from the DB Console, metrics which measure S When cluster virtualization is enabled, [backup]({% link {{ page.version.version }}/backup.md %}) and [restore]({% link {{ page.version.version }}/restore.md %}) commands are scoped to the virtual cluster by default. -### Back up a virtual cluster +Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. If needed, you can [restore](#restore-a-virtual-cluster) these backups to a new app VC. Use the following process to back up your app VC. -To back up a virtual cluster: +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with the `admin` role on the app VC: -1. [Connect to the virtual cluster](#connect-to-a-virtual-cluster) you want to back up as a user with the `admin` role on the virtual cluster. -1. [Back up the cluster]({% link {{ page.version.version }}/backup.md %}). Only the virtual cluster's data and settings are included in the backup, and data and settings for other virtual clusters or for the system virtual cluster is omitted. + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ -For details about restoring a backup of a virtual cluster, refer to [Restore a virtual cluster](#restore-a-virtual-cluster). +1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster): -### Back up the entire cluster + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP INTO 'external://backup_s3' AS OF SYSTEM TIME '-10s'; + ~~~ -To back up the entire CockroachDB cluster, including all virtual clusters and the system virtual cluster: + {% include {{ page.version.version }}/backups/backup-storage-collision.md %} -1. [Connect to the system virtual cluster](#connect-to-the-system-virtual-cluster) as a user with the `admin` role on the system virtual cluster. -1. [Back up the cluster]({% link {{ page.version.version }}/backup.md %}), and include the `INCLUDE_ALL_SECONDARY_TENANTS` flag in the `BACKUP` command. All virtual clusters and the system virtual cluster are included in the backup. +You can also back up your system VC to preserve metadata such as users and cluster settings. Use the following process to back up your system VC. + +1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with the `admin` role on the system VC: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster): + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP INTO 'external://backup_s3' AS OF SYSTEM TIME '-10s'; + ~~~ + + {% include {{ page.version.version }}/backups/backup-storage-collision.md %} ### Restore a virtual cluster @@ -147,13 +171,6 @@ To restore only a virtual cluster: 1. [Connect to the destination virtual cluster](#connect-to-a-virtual-cluster) as a user with the `admin` role on the virtual cluster. 1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}). Only the virtual cluster's data and settings are restored. -### Restore the entire cluster - -To restore the entire CockroachDB cluster, including all virtual clusters and the system virtual cluster: - -1. [Connect to the destination system virtual cluster](#connect-to-the-system-virtual-cluster) as a user with the `admin` role on the system virtual cluster. -1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}) from a backup that included the the `INCLUDE_ALL_SECONDARY_VIRTUAL_CLUSTERS` flag. All virtual clusters and the system virtual cluster are restored. - ## Configure cluster settings When [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) is enabled, each [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) is scoped to either a virtual cluster or the system virtual cluster. From 295db295dbe07cb7966e66a9217db7e4552837eb Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Mon, 10 Nov 2025 13:45:32 -0500 Subject: [PATCH 2/6] Added more sections Added sections for each level of backup and for schedules, as well as other changes from review --- .../v25.4/backups/backup-storage-collision.md | 2 +- .../v25.4/cluster-virtualization-overview.md | 2 +- .../v25.4/work-with-virtual-clusters.md | 150 ++++++++++++++++-- 3 files changed, 137 insertions(+), 17 deletions(-) diff --git a/src/current/_includes/v25.4/backups/backup-storage-collision.md b/src/current/_includes/v25.4/backups/backup-storage-collision.md index c52cc1524e5..440c9934174 100644 --- a/src/current/_includes/v25.4/backups/backup-storage-collision.md +++ b/src/current/_includes/v25.4/backups/backup-storage-collision.md @@ -1 +1 @@ -You will encounter an error if you run multiple [backup collections]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#backup-collections) to the same storage URI. Each collection's URI must be unique. \ No newline at end of file +You will encounter an error if you run multiple [backup collections]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#backup-collections) to the same storage URI. Backup collections can contain multiple full and incremental backups, but each collection's URI must be unique. If you are using backup schedules, each schedule must have a unique URI. \ No newline at end of file diff --git a/src/current/v25.4/cluster-virtualization-overview.md b/src/current/v25.4/cluster-virtualization-overview.md index 51332d3dc02..8e13e3e46e2 100644 --- a/src/current/v25.4/cluster-virtualization-overview.md +++ b/src/current/v25.4/cluster-virtualization-overview.md @@ -66,7 +66,7 @@ When cluster virtualization is enabled, [backup]({% link {{ page.version.version - If your deployment contains system-level customizations, you can take a separate backup of the system virtual cluster to capture them. - A backup of a virtual cluster can be restored as a virtual cluster in any CockroachDB cluster with cluster virtualization enabled. -For more details about backing up and restoring a cluster with cluster virtualization enabled, refer to [Work with virtual clusters]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#disaster-recovery). +For more details about backing up and restoring a cluster with cluster virtualization enabled, refer to [Work with virtual clusters]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#backup-and-restore). {{site.data.alerts.callout_success}} For details about configuring and using PCR for disaster recovery, refer to [Physical Cluster Replication Overview]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}). diff --git a/src/current/v25.4/work-with-virtual-clusters.md b/src/current/v25.4/work-with-virtual-clusters.md index edb0248915e..b8516397d3c 100644 --- a/src/current/v25.4/work-with-virtual-clusters.md +++ b/src/current/v25.4/work-with-virtual-clusters.md @@ -114,13 +114,17 @@ sql_txn_commit_count{tenant="demo"} 0 When connected to a virtual cluster from the DB Console, metrics which measure SQL and related activity show data scoped to the virtual cluster. All other metrics are collected system-wide and display the same data on all virtual clusters including the system virtual cluster. -## Disaster recovery +## Backup and restore -When cluster virtualization is enabled, [backup]({% link {{ page.version.version }}/backup.md %}) and [restore]({% link {{ page.version.version }}/restore.md %}) commands are scoped to the virtual cluster by default. +Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. -Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. If needed, you can [restore](#restore-a-virtual-cluster) these backups to a new app VC. Use the following process to back up your app VC. +### Create a backup schedule for your app VC -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with the `admin` role on the app VC: +Cockroach Labs recommends using [backup schedules]({% link {{ page.version.version }}/create-schedule-for-backup.md %}) to automate full and incremental backups of your data. + +Use the following process to create a schedule for a cluster-level backup of your app VC. In this example, the schedule takes revision history for the backup every day at midnight. + +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -129,18 +133,127 @@ Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.v --certs-dir "certs" ~~~ -1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster): +1. [Create a backup schedule]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#create-a-scheduled-backup-for-a-cluster): {% include_cached copy-clipboard.html %} ~~~ sql - BACKUP INTO 'external://backup_s3' AS OF SYSTEM TIME '-10s'; + CREATE SCHEDULE schedule_label + FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' + WITH revision_history + RECURRING '@daily'; + ~~~ + + ~~~ + schedule_id | name | status | first_run | schedule | backup_stmt + ---------------------+----------------+------------------------------------------------+----------------------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------- + 588796190000218113 | schedule_label | PAUSED: Waiting for initial backup to complete | NULL | @daily | BACKUP INTO LATEST IN 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached + 588796190012702721 | schedule_label | ACTIVE | 2020-09-10 16:52:17.280821+00:00 | @weekly | BACKUP INTO 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached + (2 rows) ~~~ {% include {{ page.version.version }}/backups/backup-storage-collision.md %} +For information on scheduling backups at different levels or with other options, consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}). + +### Back up your app VC + +Use the following process to take a one-off full backup of your app VC. + +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster): + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP INTO 'external://backup_s3/app' AS OF SYSTEM TIME '-10s'; + ~~~ + +### Back up a database from your app VC + +Use the following process to take a one-off database-level backup on your app VC. + +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-a-database) a single database: + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP DATABASE bank INTO 'external://backup_s3/app/db' AS OF SYSTEM TIME '-10s'; + ~~~ + + Or back up multiple databases: + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP DATABASE bank, employees INTO 'external://backup_s3/app/db' AS OF SYSTEM TIME '-10s'; + ~~~ + +### Back up a table or view from your app VC + +Use the following procecss to take a one-off table-level or view-level backup on your app VC. + +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view) a single table or view: + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP bank.customers INTO 'external://backup_s3/app/table' AS OF SYSTEM TIME '-10s'; + ~~~ + + Or back up multiple tables: + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP bank.customers, bank.accounts INTO 'external://backup_s3/app/table' AS OF SYSTEM TIME '-10s'; + ~~~ + +### Back up a schema from your app VC + +Use the following procecss to take a one-off schema-level backup on your app VC using a wildcard (`*`). + +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-all-tables-in-a-schema) all tables in a schema: + + {% include_cached copy-clipboard.html %} + ~~~ sql + BACKUP test_schema.* INTO 'external://backup_s3/app/schema' AS OF SYSTEM TIME '-10s'; + ~~~ + +### Back up your system VC + You can also back up your system VC to preserve metadata such as users and cluster settings. Use the following process to back up your system VC. -1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with the `admin` role on the system VC: +1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the system VC. In this example the user has the `BACKUP` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -153,23 +266,30 @@ You can also back up your system VC to preserve metadata such as users and clust {% include_cached copy-clipboard.html %} ~~~ sql - BACKUP INTO 'external://backup_s3' AS OF SYSTEM TIME '-10s'; + BACKUP INTO 'external://backup_s3/system' AS OF SYSTEM TIME '-10s'; ~~~ {% include {{ page.version.version }}/backups/backup-storage-collision.md %} ### Restore a virtual cluster -You can restore a backup of a virtual cluster to: +If needed, you can restore backups to a new app VC with no user-created databases or tables. To restore your app VC from the latest full backup: -- The original virtual cluster on the original CockroachDB cluster. -- A different virtual cluster on the original CockroachDB cluster. -- A different virtual cluster on a different CockroachDB cluster with cluster virtualization enabled. +1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the system VC. In this example the user has the `RESTORE` privilege. -To restore only a virtual cluster: + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql --url \ + "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ + --certs-dir "certs" + ~~~ + +1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}): -1. [Connect to the destination virtual cluster](#connect-to-a-virtual-cluster) as a user with the `admin` role on the virtual cluster. -1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}). Only the virtual cluster's data and settings are restored. + {% include_cached copy-clipboard.html %} + ~~~ sql + RESTORE FROM LATEST IN 's3://bucket/path?AUTH=implicit'; + ~~~ ## Configure cluster settings From 2b3fc7e481197b60e9936c1896b0d8efdd42d35d Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 18 Nov 2025 10:51:28 -0500 Subject: [PATCH 3/6] Second review Changes from second round of reviews --- .../v25.4/cluster-virtualization-overview.md | 4 +- .../v25.4/work-with-virtual-clusters.md | 89 ++----------------- 2 files changed, 12 insertions(+), 81 deletions(-) diff --git a/src/current/v25.4/cluster-virtualization-overview.md b/src/current/v25.4/cluster-virtualization-overview.md index 8e13e3e46e2..49b9e844d20 100644 --- a/src/current/v25.4/cluster-virtualization-overview.md +++ b/src/current/v25.4/cluster-virtualization-overview.md @@ -58,7 +58,9 @@ To upgrade to a new major version when cluster virtualization is enabled, you mu For details, refer to [Work with virtual clusters]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#upgrade-a-cluster). -### Disaster recovery +### Backup and restore + +Having a [disaster recovery]({% link {{ page.version.version }}/disaster-recovery-overview.md %}) plan is important to recover from unforseen incidents and minimize downtime and data loss. When cluster virtualization is enabled, [backup]({% link {{ page.version.version }}/backup.md %}) and [restore]({% link {{ page.version.version }}/restore.md %}) commands are scoped to a virtual cluster. This means that: diff --git a/src/current/v25.4/work-with-virtual-clusters.md b/src/current/v25.4/work-with-virtual-clusters.md index b8516397d3c..c56766657f7 100644 --- a/src/current/v25.4/work-with-virtual-clusters.md +++ b/src/current/v25.4/work-with-virtual-clusters.md @@ -116,13 +116,13 @@ When connected to a virtual cluster from the DB Console, metrics which measure S ## Backup and restore -Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. +Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. You can also back up your system VC to preserve metadata such as users and cluster settings, but this data is usually not critical. ### Create a backup schedule for your app VC Cockroach Labs recommends using [backup schedules]({% link {{ page.version.version }}/create-schedule-for-backup.md %}) to automate full and incremental backups of your data. -Use the following process to create a schedule for a cluster-level backup of your app VC. In this example, the schedule takes revision history for the backup every day at midnight. +Use the following process to create a schedule for a cluster-level backup of your app VC. In this example, the schedule takes an incremental backup every day at midnight, and a full backup weekly. Consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#parameters) for a full list of backup schedule options. 1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. @@ -139,7 +139,6 @@ Use the following process to create a schedule for a cluster-level backup of you ~~~ sql CREATE SCHEDULE schedule_label FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' - WITH revision_history RECURRING '@daily'; ~~~ @@ -155,9 +154,9 @@ Use the following process to create a schedule for a cluster-level backup of you For information on scheduling backups at different levels or with other options, consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}). -### Back up your app VC +### Take a one-off backup of your app VC -Use the following process to take a one-off full backup of your app VC. +Use the following process to take a one-off full backup of your app VC. Even if you are using backup schedules, this can be useful if you want to create a separate copy. 1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. @@ -175,79 +174,7 @@ Use the following process to take a one-off full backup of your app VC. BACKUP INTO 'external://backup_s3/app' AS OF SYSTEM TIME '-10s'; ~~~ -### Back up a database from your app VC - -Use the following process to take a one-off database-level backup on your app VC. - -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach sql --url \ - "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ - --certs-dir "certs" - ~~~ - -1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-a-database) a single database: - - {% include_cached copy-clipboard.html %} - ~~~ sql - BACKUP DATABASE bank INTO 'external://backup_s3/app/db' AS OF SYSTEM TIME '-10s'; - ~~~ - - Or back up multiple databases: - - {% include_cached copy-clipboard.html %} - ~~~ sql - BACKUP DATABASE bank, employees INTO 'external://backup_s3/app/db' AS OF SYSTEM TIME '-10s'; - ~~~ - -### Back up a table or view from your app VC - -Use the following procecss to take a one-off table-level or view-level backup on your app VC. - -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach sql --url \ - "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ - --certs-dir "certs" - ~~~ - -1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view) a single table or view: - - {% include_cached copy-clipboard.html %} - ~~~ sql - BACKUP bank.customers INTO 'external://backup_s3/app/table' AS OF SYSTEM TIME '-10s'; - ~~~ - - Or back up multiple tables: - - {% include_cached copy-clipboard.html %} - ~~~ sql - BACKUP bank.customers, bank.accounts INTO 'external://backup_s3/app/table' AS OF SYSTEM TIME '-10s'; - ~~~ - -### Back up a schema from your app VC - -Use the following procecss to take a one-off schema-level backup on your app VC using a wildcard (`*`). - -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. - - {% include_cached copy-clipboard.html %} - ~~~ shell - cockroach sql --url \ - "postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \ - --certs-dir "certs" - ~~~ - -1. [Back up]({% link {{ page.version.version }}/backup.md %}#back-up-all-tables-in-a-schema) all tables in a schema: - - {% include_cached copy-clipboard.html %} - ~~~ sql - BACKUP test_schema.* INTO 'external://backup_s3/app/schema' AS OF SYSTEM TIME '-10s'; - ~~~ +You can also take one-off backups of a single [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database) or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view) on your app VC. For more information on backup options, consult [BACKUP]({% link {{ page.version.version }}/backup.md %}). ### Back up your system VC @@ -273,9 +200,9 @@ You can also back up your system VC to preserve metadata such as users and clust ### Restore a virtual cluster -If needed, you can restore backups to a new app VC with no user-created databases or tables. To restore your app VC from the latest full backup: +If needed, you can restore a full backup to a new app VC with no user-created databases or tables. To restore your app VC from the latest full backup: -1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the system VC. In this example the user has the `RESTORE` privilege. +1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `RESTORE` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -291,6 +218,8 @@ If needed, you can restore backups to a new app VC with no user-created database RESTORE FROM LATEST IN 's3://bucket/path?AUTH=implicit'; ~~~ +You can also restore a [database-level]({% link {{ page.version.version }}/restore.md %}#restore-a-database) or [table-level]({% link {{ page.version.version }}/restore.md %}#restore-a-table) backup to the same app VC on which you created it. For more information on restore options, consult [RESTORE]({% link {{ page.version.version }}/restore.md %}). + ## Configure cluster settings When [cluster virtualization]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}) is enabled, each [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) is scoped to either a virtual cluster or the system virtual cluster. From c26d7c0579c1d075547cba15c5f2c9832d410eea Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 18 Nov 2025 11:09:13 -0500 Subject: [PATCH 4/6] Broken link broken link --- src/current/releases/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/current/releases/index.md b/src/current/releases/index.md index 58ce68a86d4..679ec84232a 100644 --- a/src/current/releases/index.md +++ b/src/current/releases/index.md @@ -116,7 +116,6 @@ A cluster that is upgraded to an alpha binary of CockroachDB or a binary that wa | [v24.2]({% link releases/unsupported-versions.md %}#v24-2) | Innovation | 2024-08-12 | | [v24.1](#v24-1) | Regular | 2024-05-20 | | [v23.2](#v23-2) | Regular | 2024-02-05 | -| [v23.1](#v23-1) | Regular | 2023-05-15 | ### Upcoming releases From 5151083d9d86249f7deefe91f99321eaf6ffadc7 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Thu, 20 Nov 2025 11:07:27 -0500 Subject: [PATCH 5/6] More small changes from review More small changes from review --- src/current/v25.4/work-with-virtual-clusters.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/current/v25.4/work-with-virtual-clusters.md b/src/current/v25.4/work-with-virtual-clusters.md index c56766657f7..6896747588f 100644 --- a/src/current/v25.4/work-with-virtual-clusters.md +++ b/src/current/v25.4/work-with-virtual-clusters.md @@ -116,13 +116,13 @@ When connected to a virtual cluster from the DB Console, metrics which measure S ## Backup and restore -Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data and settings are included in these backups, and data and settings for other virtual clusters or for the _system virtual cluster (system VC)_ are omitted. You can also back up your system VC to preserve metadata such as users and cluster settings, but this data is usually not critical. +Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data is included in these backups, and data for other virtual clusters or for the _system virtual cluster (system VC)_ is omitted. You can also back up your system VC to preserve metadata related to your system VC, but this data is usually not critical. ### Create a backup schedule for your app VC Cockroach Labs recommends using [backup schedules]({% link {{ page.version.version }}/create-schedule-for-backup.md %}) to automate full and incremental backups of your data. -Use the following process to create a schedule for a cluster-level backup of your app VC. In this example, the schedule takes an incremental backup every day at midnight, and a full backup weekly. Consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#parameters) for a full list of backup schedule options. +Use the following process to create a schedule for a backup of your app VC. In this example, the schedule takes an incremental backup every day at midnight, and a full backup weekly. Consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#parameters) for a full list of backup schedule options. 1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. @@ -133,7 +133,7 @@ Use the following process to create a schedule for a cluster-level backup of you --certs-dir "certs" ~~~ -1. [Create a backup schedule]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#create-a-scheduled-backup-for-a-cluster): +1. [Create a backup schedule]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#create-a-scheduled-backup-for-a-cluster). This example is for a cluster-level backup: {% include_cached copy-clipboard.html %} ~~~ sql @@ -145,8 +145,8 @@ Use the following process to create a schedule for a cluster-level backup of you ~~~ schedule_id | name | status | first_run | schedule | backup_stmt ---------------------+----------------+------------------------------------------------+----------------------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------------------------- - 588796190000218113 | schedule_label | PAUSED: Waiting for initial backup to complete | NULL | @daily | BACKUP INTO LATEST IN 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached - 588796190012702721 | schedule_label | ACTIVE | 2020-09-10 16:52:17.280821+00:00 | @weekly | BACKUP INTO 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached + 588796190000218113 | schedule_label | PAUSED: Waiting for initial backup to complete | NULL | @daily | BACKUP INTO LATEST IN 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x', detached + 588796190012702721 | schedule_label | ACTIVE | 2020-09-10 16:52:17.280821+00:00 | @weekly | BACKUP INTO 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x', detached (2 rows) ~~~ @@ -174,11 +174,11 @@ Use the following process to take a one-off full backup of your app VC. Even if BACKUP INTO 'external://backup_s3/app' AS OF SYSTEM TIME '-10s'; ~~~ -You can also take one-off backups of a single [database]({% link {{ page.version.version }}/backup.md %}#back-up-a-database) or [table]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view) on your app VC. For more information on backup options, consult [BACKUP]({% link {{ page.version.version }}/backup.md %}). +You can also take one-off backups of [databases]({% link {{ page.version.version }}/backup.md %}#back-up-a-database) or [tables]({% link {{ page.version.version }}/backup.md %}#back-up-a-table-or-view) on your app VC. For more information on backup options, consult [BACKUP]({% link {{ page.version.version }}/backup.md %}). ### Back up your system VC -You can also back up your system VC to preserve metadata such as users and cluster settings. Use the following process to back up your system VC. +You can also back up your system VC to preserve metadata stored in the system VC. Use the following process to back up your system VC. 1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the system VC. In this example the user has the `BACKUP` privilege. @@ -200,7 +200,7 @@ You can also back up your system VC to preserve metadata such as users and clust ### Restore a virtual cluster -If needed, you can restore a full backup to a new app VC with no user-created databases or tables. To restore your app VC from the latest full backup: +If needed, you can restore a backup to a new app VC. For cluster-level restores, the new app VC must have no user-created databases or tables. To restore your app VC from the latest backup: 1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `RESTORE` privilege. From 01b60815b840da5df7a1ce487630f4a188307a89 Mon Sep 17 00:00:00 2001 From: Peach Leach <87079419+peachdawnleach@users.noreply.github.com> Date: Mon, 24 Nov 2025 11:06:26 -0500 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Florence Morris <58752716+florence-crl@users.noreply.github.com> --- .../v25.4/cluster-virtualization-overview.md | 2 +- .../v25.4/work-with-virtual-clusters.md | 22 +++++++++---------- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/current/v25.4/cluster-virtualization-overview.md b/src/current/v25.4/cluster-virtualization-overview.md index 49b9e844d20..0b0cce6f645 100644 --- a/src/current/v25.4/cluster-virtualization-overview.md +++ b/src/current/v25.4/cluster-virtualization-overview.md @@ -60,7 +60,7 @@ For details, refer to [Work with virtual clusters]({% link {{ page.version.versi ### Backup and restore -Having a [disaster recovery]({% link {{ page.version.version }}/disaster-recovery-overview.md %}) plan is important to recover from unforseen incidents and minimize downtime and data loss. +Having a [disaster recovery]({% link {{ page.version.version }}/disaster-recovery-overview.md %}) plan is important to recover from unforeseen incidents and to minimize downtime and data loss. When cluster virtualization is enabled, [backup]({% link {{ page.version.version }}/backup.md %}) and [restore]({% link {{ page.version.version }}/restore.md %}) commands are scoped to a virtual cluster. This means that: diff --git a/src/current/v25.4/work-with-virtual-clusters.md b/src/current/v25.4/work-with-virtual-clusters.md index 6896747588f..8276c712ba3 100644 --- a/src/current/v25.4/work-with-virtual-clusters.md +++ b/src/current/v25.4/work-with-virtual-clusters.md @@ -116,15 +116,15 @@ When connected to a virtual cluster from the DB Console, metrics which measure S ## Backup and restore -Cockroach Labs recommends that you regularly [back up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data is included in these backups, and data for other virtual clusters or for the _system virtual cluster (system VC)_ is omitted. You can also back up your system VC to preserve metadata related to your system VC, but this data is usually not critical. +Cockroach Labs recommends regularly [backing up]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups) your data. When using virtual clusters, perform backups on the _application virtual cluster (app VC)_. Only the app VC's data is included in these backups. Data from other virtual clusters or the _system virtual cluster (system VC)_ is omitted. You can also back up your system VC to preserve its metadata, although this data is usually not critical. ### Create a backup schedule for your app VC Cockroach Labs recommends using [backup schedules]({% link {{ page.version.version }}/create-schedule-for-backup.md %}) to automate full and incremental backups of your data. -Use the following process to create a schedule for a backup of your app VC. In this example, the schedule takes an incremental backup every day at midnight, and a full backup weekly. Consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#parameters) for a full list of backup schedule options. +Follow these steps to create a backup schedule for your app VC. In this example, the schedule takes an incremental backup every day at midnight, and a full backup weekly. Consult [CREATE SCHEDULE FOR BACKUP]({% link {{ page.version.version }}/create-schedule-for-backup.md %}#parameters) for a full list of backup schedule options. -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with the [required privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges). In this example, the user has the `BACKUP` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -138,7 +138,7 @@ Use the following process to create a schedule for a backup of your app VC. In t {% include_cached copy-clipboard.html %} ~~~ sql CREATE SCHEDULE schedule_label - FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' + FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID={aws_access_key_id}&AWS_SECRET_ACCESS_KEY={aws_secret_access_key}' RECURRING '@daily'; ~~~ @@ -156,9 +156,9 @@ For information on scheduling backups at different levels or with other options, ### Take a one-off backup of your app VC -Use the following process to take a one-off full backup of your app VC. Even if you are using backup schedules, this can be useful if you want to create a separate copy. +Follow these steps to take a one-off full backup of your app VC. Even if you use backup schedules, taking a one-off backup can be useful for creating a separate copy. -1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `BACKUP` privilege. +1. [Connect](#connect-to-a-virtual-cluster) to the app VC as a user with the [required privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges). In this example, the user has the `BACKUP` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -178,9 +178,9 @@ You can also take one-off backups of [databases]({% link {{ page.version.version ### Back up your system VC -You can also back up your system VC to preserve metadata stored in the system VC. Use the following process to back up your system VC. +You can also back up your system VC to preserve its stored metadata. Follow these steps to back up your system VC. -1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the system VC. In this example the user has the `BACKUP` privilege. +1. [Connect](#connect-to-the-system-virtual-cluster) to the system VC as a user with the [required privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges). In this example the user has the `BACKUP` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -200,9 +200,9 @@ You can also back up your system VC to preserve metadata stored in the system VC ### Restore a virtual cluster -If needed, you can restore a backup to a new app VC. For cluster-level restores, the new app VC must have no user-created databases or tables. To restore your app VC from the latest backup: +If needed, you can restore a backup to a new app VC. For cluster-level restores, the new app VC must not contain any user-created databases or tables. To restore your app VC from the latest backup: -1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with [supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the app VC. In this example the user has the `RESTORE` privilege. +1. [Connect to the destination app VC](#connect-to-a-virtual-cluster) as a user with the [required privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges). In this example the user has the `RESTORE` privilege. {% include_cached copy-clipboard.html %} ~~~ shell @@ -218,7 +218,7 @@ If needed, you can restore a backup to a new app VC. For cluster-level restores, RESTORE FROM LATEST IN 's3://bucket/path?AUTH=implicit'; ~~~ -You can also restore a [database-level]({% link {{ page.version.version }}/restore.md %}#restore-a-database) or [table-level]({% link {{ page.version.version }}/restore.md %}#restore-a-table) backup to the same app VC on which you created it. For more information on restore options, consult [RESTORE]({% link {{ page.version.version }}/restore.md %}). +You can also restore a [database-level]({% link {{ page.version.version }}/restore.md %}#restore-a-database) or [table-level]({% link {{ page.version.version }}/restore.md %}#restore-a-table) backup to the same app VC where it was created. For more information on restore options, consult [RESTORE]({% link {{ page.version.version }}/restore.md %}). ## Configure cluster settings