diff --git a/src/current/v23.1/restore.md b/src/current/v23.1/restore.md index 57111b8bbd1..e61bad9b7f0 100644 --- a/src/current/v23.1/restore.md +++ b/src/current/v23.1/restore.md @@ -127,8 +127,9 @@ You can control `RESTORE` behavior using any of the following in the `restore_op New in v23.1:`skip_missing_udfs` | N/A | Must be used when restoring a table with referenced [UDF]({% link {{ page.version.version }}/user-defined-functions.md %}) dependencies. Any column's `DEFAULT` expression using UDFs is dropped.

Example: `WITH skip_missing_udfs` `encryption_passphrase` | Passphrase used to create the [encrypted backup]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) | The passphrase used to decrypt the file(s) that were encrypted by the [`BACKUP`]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) statement. `DETACHED` | N/A | When `RESTORE` runs with `DETACHED`, the job will execute asynchronously. The job ID is returned after the restore job creation completes. Note that with `DETACHED` specified, further job information and the job completion status will not be returned. For more on the differences between the returned job data, see the [example]({% link {{ page.version.version }}/restore.md %}#restore-a-backup-asynchronously) below. To check on the job status, use the [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}) statement.

To run a restore within a [transaction]({% link {{ page.version.version }}/transactions.md %}), use the `DETACHED` option. -`debug_pause_on` | `"error" ` | Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job.

Example: `WITH debug_pause_on='error'` -`incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with.

See [Restore incremental backups](#restore-a-specific-full-or-incremental-backup) for more detail. +New in v23.1.12:`EXECUTION LOCALITY` | Key-value pairs | Restricts the execution of the restore to nodes that match the defined [locality filter]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) requirements.

Example: `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'` +`debug_pause_on` | `"error" ` | Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job.

Example: `WITH debug_pause_on='error'` +`incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with.

Refer to [Restore incremental backups](#restore-the-most-recent-full-or-incremental-backup) for more detail. `schema_only` | N/A | Verify that a backup is valid by running `RESTORE ... schema_only`, which will restore the backed-up schema without any user data. Refer to [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-a-backup-is-restorable) for detail and an example. `verify_backup_table_data` | N/A | Run a `schema_only` restore **and** have the restore read all user data from external storage, verify checksums, and discard the user data before writing it to disk. You must also include the `schema_only` option in the `RESTORE` statement with `verify_backup_table_data`. For more detail, see [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-backup-table-data-is-restorable). diff --git a/src/current/v23.1/take-locality-restricted-backups.md b/src/current/v23.1/take-locality-restricted-backups.md index 986bbe572f0..9745a2542ec 100644 --- a/src/current/v23.1/take-locality-restricted-backups.md +++ b/src/current/v23.1/take-locality-restricted-backups.md @@ -7,6 +7,8 @@ docs_area: manage {% include_cached new-in.html version="v23.1" %} The `EXECUTION LOCALITY` option allows you to restrict the nodes that can execute a [backup]({% link {{ page.version.version }}/backup.md %}) job by using a [locality filter]({% link {{ page.version.version }}/cockroach-start.md %}#locality) when you create the backup. This will pin the [coordination of the backup job]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) and the nodes that [process the row data]({% link {{ page.version.version }}/backup-architecture.md %}#export-phase) to the defined locality filter. +{% include_cached new-in.html version="v23.1.12" %} Pass the `WITH EXECUTION LOCALITY` option for [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) to restrict execution of the job to nodes with matching localities. + Defining an execution locality for a backup job is useful in the following cases: - When nodes in a cluster operate in different locality tiers, networking rules can restrict nodes from accessing a storage bucket. For an example, refer to [Access backup storage restricted by network rules](#access-backup-storage-restricted-by-network-rules). @@ -31,11 +33,12 @@ To specify the locality filter for the coordinating node, run `EXECUTION LOCALIT BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'region={region},cloud={cloud}'; ~~~ -When you run a backup that uses `EXECUTION LOCALITY`, consider the following: +When you run a backup or restore that uses `EXECUTION LOCALITY`, consider the following: -- The backup job will fail if no nodes match the locality filter. -- The backup job may take slightly more time to start, because it must select the node that coordinates the backup (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). -- Even after a backup job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter. +- `RESTORE` with the `EXECUTION LOCALITY` option is available from v23.1.12. +- The backup or restore job will fail if no nodes match the locality filter. +- The backup or restore job may take slightly more time to start, because it must select the node that coordinates the backup or restore (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). +- Even after a backup or restore job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter. - If the job is created on a node that does not match the locality filter, you will receive an error even when the **job creation was successful**. This error indicates that the job execution moved to another node. To avoid this error when creating a manual job (as opposed to a [scheduled job]({% link {{ page.version.version }}/create-schedule-for-backup.md %})), you can use the [`DETACHED`]({% link {{ page.version.version }}/backup.md %}#detached) option with `EXECUTION LOCALITY`. Then, use the [`SHOW JOB WHEN COMPLETE`]({% link {{ page.version.version }}/show-jobs.md %}#show-job-when-complete) statement to determine when the job has finished. For more details, refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). ## Examples @@ -61,7 +64,14 @@ For example, you can pin the execution of the backup job to `us-west-1`: BACKUP DATABASE {database} INTO 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED; ~~~ -Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) page for further detail on other parameters and options. +{% include_cached new-in.html version="v23.1.12" %} To restore the most recent locality-restricted backup: + +{% include_cached copy-clipboard.html %} +~~~ sql +RESTORE FROM LATEST IN 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED; +~~~ + +Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) and [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) pages for further detail on other parameters and options. ### Create a non-primary region for backup jobs diff --git a/src/current/v23.2/restore.md b/src/current/v23.2/restore.md index e6977408be0..1dcfd1e0c12 100644 --- a/src/current/v23.2/restore.md +++ b/src/current/v23.2/restore.md @@ -127,6 +127,7 @@ You can control `RESTORE` behavior using any of the following in the `restore_op `skip_missing_udfs` | N/A | Must be used when restoring a table with referenced [UDF]({% link {{ page.version.version }}/user-defined-functions.md %}) dependencies. Any column's `DEFAULT` expression using UDFs is dropped.

Example: `WITH skip_missing_udfs` `encryption_passphrase` | Passphrase used to create the [encrypted backup]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) | The passphrase used to decrypt the file(s) that were encrypted by the [`BACKUP`]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) statement. `DETACHED` | N/A | When `RESTORE` runs with `DETACHED`, the job will execute asynchronously. The job ID is returned after the restore job creation completes. Note that with `DETACHED` specified, further job information and the job completion status will not be returned. For more on the differences between the returned job data, see the [example]({% link {{ page.version.version }}/restore.md %}#restore-a-backup-asynchronously) below. To check on the job status, use the [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}) statement.

To run a restore within a [transaction]({% link {{ page.version.version }}/transactions.md %}), use the `DETACHED` option. +New in v23.2:`EXECUTION LOCALITY` | Key-value pairs | Restricts the execution of the restore to nodes that match the defined [locality filter]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) requirements.

Example: `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'` `debug_pause_on` | `"error" ` | Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job.

Example: `WITH debug_pause_on='error'` `incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with.

See [Restore incremental backups](#restore-a-specific-full-or-incremental-backup) for more detail. `schema_only` | N/A | Verify that a backup is valid by running `RESTORE ... schema_only`, which will restore the backed-up schema without any user data. Refer to [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-a-backup-is-restorable) for detail and an example. diff --git a/src/current/v23.2/take-locality-restricted-backups.md b/src/current/v23.2/take-locality-restricted-backups.md index a7f4bee9cf8..0fb069e1608 100644 --- a/src/current/v23.2/take-locality-restricted-backups.md +++ b/src/current/v23.2/take-locality-restricted-backups.md @@ -7,6 +7,8 @@ docs_area: manage The `EXECUTION LOCALITY` option allows you to restrict the nodes that can execute a [backup]({% link {{ page.version.version }}/backup.md %}) job by using a [locality filter]({% link {{ page.version.version }}/cockroach-start.md %}#locality) when you create the backup. This will pin the [coordination of the backup job]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) and the nodes that [process the row data]({% link {{ page.version.version }}/backup-architecture.md %}#export-phase) to the defined locality filter. +{% include_cached new-in.html version="v23.2" %} Pass the `WITH EXECUTION LOCALITY` option for [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) to restrict execution of the job to nodes with matching localities. + Defining an execution locality for a backup job is useful in the following cases: - When nodes in a cluster operate in different locality tiers, networking rules can restrict nodes from accessing a storage bucket. For an example, refer to [Access backup storage restricted by network rules](#access-backup-storage-restricted-by-network-rules). @@ -31,11 +33,11 @@ To specify the locality filter for the coordinating node, run `EXECUTION LOCALIT BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'region={region},cloud={cloud}'; ~~~ -When you run a backup that uses `EXECUTION LOCALITY`, consider the following: +When you run a backup or restore that uses `EXECUTION LOCALITY`, consider the following: -- The backup job will fail if no nodes match the locality filter. -- The backup job may take slightly more time to start, because it must select the node that coordinates the backup (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). -- Even after a backup job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter. +- The backup or restore job will fail if no nodes match the locality filter. +- The backup or restore job may take slightly more time to start, because it must select the node that coordinates the backup or restore (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). +- Even after a backup or restore job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter. - If the job is created on a node that does not match the locality filter, you will receive an error even when the **job creation was successful**. This error indicates that the job execution moved to another node. To avoid this error when creating a manual job (as opposed to a [scheduled job]({% link {{ page.version.version }}/create-schedule-for-backup.md %})), you can use the [`DETACHED`]({% link {{ page.version.version }}/backup.md %}#detached) option with `EXECUTION LOCALITY`. Then, use the [`SHOW JOB WHEN COMPLETE`]({% link {{ page.version.version }}/show-jobs.md %}#show-job-when-complete) statement to determine when the job has finished. For more details, refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option). ## Examples @@ -61,7 +63,14 @@ For example, you can pin the execution of the backup job to `us-west-1`: BACKUP DATABASE {database} INTO 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED; ~~~ -Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) page for further detail on other parameters and options. +To restore the most recent locality-restricted backup: + +{% include_cached copy-clipboard.html %} +~~~ sql +RESTORE FROM LATEST IN 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED; +~~~ + +Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) and [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) pages for further detail on other parameters and options. ### Create a non-primary region for backup jobs