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