Skip to content

Commit 5b8ed6a

Browse files
peachdawnleachflorence-crl
peachdawnleach
and
florence-crl
authored
Restructured DR backup section for clarity and thoroughness (#20873)
* Restructured section Restructured backup and dr section for clarity and thoroughness * Added more sections Added sections for each level of backup and for schedules, as well as other changes from review * Second review Changes from second round of reviews * Broken link broken link * More small changes from review More small changes from review * Apply suggestions from code review Co-authored-by: Florence Morris <[email protected]> --------- Co-authored-by: Florence Morris <[email protected]>
1 parent af85aec commit 5b8ed6a

File tree

3 files changed

+94
-26
lines changed

3 files changed

+94
-26
lines changed

‎src/current/_includes/v25.4/backups/backup-storage-collision.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +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.
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. 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.

‎src/current/v25.4/cluster-virtualization-overview.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,15 +58,17 @@ To upgrade to a new major version when cluster virtualization is enabled, you mu
5858

5959
For details, refer to [Work with virtual clusters]({% link {{ page.version.version }}/work-with-virtual-clusters.md %}#upgrade-a-cluster).
6060

61-
### Disaster recovery
61+
### Backup and restore
62+
63+
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.
6264

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

6567
- A backup taken from a virtual cluster contains all data for that virtual cluster, but does not contain modifications made via the system virtual cluster such as system-level cluster settings.
6668
- If your deployment contains system-level customizations, you can take a separate backup of the system virtual cluster to capture them.
6769
- A backup of a virtual cluster can be restored as a virtual cluster in any CockroachDB cluster with cluster virtualization enabled.
6870

69-
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).
71+
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).
7072

7173
{{site.data.alerts.callout_success}}
7274
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 %}).

‎src/current/v25.4/work-with-virtual-clusters.md‎

Lines changed: 89 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -114,45 +114,111 @@ sql_txn_commit_count{tenant="demo"} 0
114114

115115
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.
116116

117-
## Disaster recovery
117+
## Backup and restore
118118

119-
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.
119+
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.
120120

121-
### Back up a virtual cluster
121+
### Create a backup schedule for your app VC
122122

123-
To back up a virtual cluster:
123+
Cockroach Labs recommends using [backup schedules]({% link {{ page.version.version }}/create-schedule-for-backup.md %}) to automate full and incremental backups of your data.
124124

125-
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.
126-
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.
125+
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.
127126

128-
For details about restoring a backup of a virtual cluster, refer to [Restore a virtual cluster](#restore-a-virtual-cluster).
127+
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.
129128

130-
### Back up the entire cluster
129+
{% include_cached copy-clipboard.html %}
130+
~~~ shell
131+
cockroach sql --url \
132+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
133+
--certs-dir "certs"
134+
~~~
131135

132-
To back up the entire CockroachDB cluster, including all virtual clusters and the system virtual cluster:
136+
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:
133137

134-
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.
135-
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.
138+
{% include_cached copy-clipboard.html %}
139+
~~~ sql
140+
CREATE SCHEDULE schedule_label
141+
FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID={aws_access_key_id}&AWS_SECRET_ACCESS_KEY={aws_secret_access_key}'
142+
RECURRING '@daily';
143+
~~~
136144

137-
### Restore a virtual cluster
145+
~~~
146+
schedule_id | name | status | first_run | schedule | backup_stmt
147+
---------------------+----------------+------------------------------------------------+----------------------------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------
148+
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
149+
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
150+
(2 rows)
151+
~~~
152+
153+
{% include {{ page.version.version }}/backups/backup-storage-collision.md %}
154+
155+
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 %}).
156+
157+
### Take a one-off backup of your app VC
158+
159+
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.
160+
161+
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.
162+
163+
{% include_cached copy-clipboard.html %}
164+
~~~ shell
165+
cockroach sql --url \
166+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
167+
--certs-dir "certs"
168+
~~~
169+
170+
1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster):
171+
172+
{% include_cached copy-clipboard.html %}
173+
~~~ sql
174+
BACKUP INTO 'external://backup_s3/app' AS OF SYSTEM TIME '-10s';
175+
~~~
138176

139-
You can restore a backup of a virtual cluster to:
177+
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 %}).
178+
179+
### Back up your system VC
180+
181+
You can also back up your system VC to preserve its stored metadata. Follow these steps to back up your system VC.
182+
183+
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.
184+
185+
{% include_cached copy-clipboard.html %}
186+
~~~ shell
187+
cockroach sql --url \
188+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full" \
189+
--certs-dir "certs"
190+
~~~
191+
192+
1. [Perform a full backup]({% link {{ page.version.version }}/backup.md %}#back-up-a-cluster):
193+
194+
{% include_cached copy-clipboard.html %}
195+
~~~ sql
196+
BACKUP INTO 'external://backup_s3/system' AS OF SYSTEM TIME '-10s';
197+
~~~
198+
199+
{% include {{ page.version.version }}/backups/backup-storage-collision.md %}
200+
201+
### Restore a virtual cluster
140202

141-
- The original virtual cluster on the original CockroachDB cluster.
142-
- A different virtual cluster on the original CockroachDB cluster.
143-
- A different virtual cluster on a different CockroachDB cluster with cluster virtualization enabled.
203+
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:
144204

145-
To restore only a virtual cluster:
205+
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.
146206

147-
1. [Connect to the destination virtual cluster](#connect-to-a-virtual-cluster) as a user with the `admin` role on the virtual cluster.
148-
1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}). Only the virtual cluster's data and settings are restored.
207+
{% include_cached copy-clipboard.html %}
208+
~~~ shell
209+
cockroach sql --url \
210+
"postgresql://root@{primary node IP or hostname}:26257?options=-ccluster={app_virtual_cluster_name}&sslmode=verify-full" \
211+
--certs-dir "certs"
212+
~~~
149213

150-
### Restore the entire cluster
214+
1. [Restore the cluster]({% link {{ page.version.version }}/restore.md %}):
151215

152-
To restore the entire CockroachDB cluster, including all virtual clusters and the system virtual cluster:
216+
{% include_cached copy-clipboard.html %}
217+
~~~ sql
218+
RESTORE FROM LATEST IN 's3://bucket/path?AUTH=implicit';
219+
~~~
153220

154-
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.
155-
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.
221+
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 %}).
156222

157223
## Configure cluster settings
158224

0 commit comments

Comments
 (0)