v26.2 previews of faster restore, improved show backups; syntax updates/removals (#23215)

Author: mikeCRL

src/current/_includes/common/sql/incremental-location-warning.md

@@ -1,3 +1,3 @@
 {{site.data.alerts.callout_danger}}
-The `incremental_location` parameter is deprecated as of v25.4 and will be removed in a future release. Until the parameter is removed, you can continue to work with existing backups that use a custom `incremental_location`.
+**Removed in v26.2**: The `incremental_location` option has been removed in v26.2, following its prior [deprecation]({% link releases/v25.4.md %}#v25-4-0-deprecations). Existing backups taken with this option cannot be restored in v26.2 or later. If you have backups that use `incremental_location`, you can only restore them using a cluster running v26.1 or earlier.
 {{site.data.alerts.end}}

src/current/_includes/v26.2/backups/advanced-examples-list.md

@@ -1,11 +1,9 @@
 For examples of advanced `BACKUP` and `RESTORE` use cases, see:
 
-- [Incremental backups with a specified destination]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups-with-explicitly-specified-destinations)
 - [Backup with revision history and point-in-time restore]({% link {{ page.version.version }}/take-backups-with-revision-history-and-restore-from-a-point-in-time.md %})
 - [Locality-aware backup and restore]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %})
 - [Encrypted backup and restore]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %})
 - [Restore into a different database]({% link {{ page.version.version }}/restore.md %}#restore-tables-into-a-different-database)
 - [Remove the foreign key before restore]({% link {{ page.version.version }}/restore.md %}#remove-the-foreign-key-before-restore)
 - [Restoring users from `system.users` backup]({% link {{ page.version.version }}/restore.md %}#restoring-users-from-system-users-backup)
-- [Show an incremental backup at a different location]({% link {{ page.version.version }}/show-backup.md %}#show-a-backup-taken-with-the-incremental-location-option)
 - [Exclude a table's data from backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#exclude-a-tables-data-from-backups)

src/current/_includes/v26.2/backups/backup-options-for-schedules.md

@@ -4,5 +4,4 @@
 `encryption_passphrase`<a name="with-encryption-passphrase"></a> | [`STRING`]({% link {{ page.version.version }}/string.md %}) | The passphrase used to [encrypt the files]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) (`BACKUP` manifest and data files) that the `BACKUP` statement generates. This same passphrase is needed to decrypt the file when it is used to [restore]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) and to list the contents of the backup when using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). There is no practical limit on the length of the passphrase.
 `detached`<a name="detached"></a>                           | [`BOOL`]({% link {{ page.version.version }}/bool.md %}) / None                   | **Note:** Backups running on a schedule have the `detached` option applied implicitly. Therefore, you cannot modify this option for scheduled backups. <br><br>When a backup runs in `detached` mode, it will execute asynchronously. The job ID will be returned after the backup [job creation]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) 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 }}/backup.md %}#run-a-backup-asynchronously). To check on the job status, use the [`SHOW JOBS`](show-jobs.html) statement.
 `EXECUTION LOCALITY` | Key-value pairs | Restricts the execution of the backup to nodes that match the defined locality filter requirements. For example, `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'`. <br><br>Refer to [Take Locality-restricted backups]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) for usage and reference detail.
-`kms`                                                            | [`STRING`]({% link {{ page.version.version }}/string.md %}) |  The URI of the cryptographic key stored in a key management service (KMS), or a comma-separated list of key URIs, used to [take and restore encrypted backups]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples). Refer to [URI Formats]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#uri-formats). The key or keys are  used to encrypt the manifest and data files that the `BACKUP` statement generates and to decrypt them during a [restore]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples) operation, and to list the contents of the backup when using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). <br/><br/>AWS KMS, Google Cloud KMS, and Azure Key Vault are supported.  
-`incremental_location`<a name="incr-location"></a> | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Create an incremental backup in a different location than the default incremental backup location. <br><br>`WITH incremental_location = 'explicit_incrementals_URI'`<br><br>See [Incremental backups with explicitly specified destinations]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups-with-explicitly-specified-destinations) for usage. <br><br> **Warning:** The `incremental_location` parameter is deprecated as of v25.4 and will be removed in a future release. Until the parameter is removed, you can continue to work with existing backups that use a custom `incremental_location`.
+`kms`                                                            | [`STRING`]({% link {{ page.version.version }}/string.md %}) |  The URI of the cryptographic key stored in a key management service (KMS), or a comma-separated list of key URIs, used to [take and restore encrypted backups]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples). Refer to [URI Formats]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#uri-formats). The key or keys are  used to encrypt the manifest and data files that the `BACKUP` statement generates and to decrypt them during a [restore]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples) operation, and to list the contents of the backup when using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). <br/><br/>AWS KMS, Google Cloud KMS, and Azure Key Vault are supported.

src/current/_includes/v26.2/backups/backup-options.md

@@ -5,5 +5,4 @@
 `detached`<a name="detached"></a>                           | [`BOOL`]({% link {{ page.version.version }}/bool.md %}) / None                   |  When a backup runs in `detached` mode, it will execute asynchronously. The job ID will be returned after the backup [job creation]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) 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 }}/backup.md %}#run-a-backup-asynchronously). To check on the job status, use the [`SHOW JOBS`](show-jobs.html) statement. Backups running on a [schedule](create-schedule-for-backup.html) have the `detached` option applied implicitly.<br><br>To run a backup within a [transaction](transactions.html), use the `detached` option.
 `EXECUTION LOCALITY` | Key-value pairs | Restricts the execution of the backup to nodes that match the defined locality filter requirements. For example, `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'`. <br><br>Refer to [Take Locality-restricted backups]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) for usage and reference detail.
 `kms`                                                            | [`STRING`]({% link {{ page.version.version }}/string.md %}) |  The URI of the cryptographic key stored in a key management service (KMS), or a comma-separated list of key URIs, used to [take and restore encrypted backups]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples). Refer to [URI Formats]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#uri-formats). The key or keys are  used to encrypt the manifest and data files that the `BACKUP` statement generates and to decrypt them during a [restore]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#examples) operation, and to list the contents of the backup when using [`SHOW BACKUP`]({% link {{ page.version.version }}/show-backup.md %}). <br/><br/>AWS KMS, Google Cloud KMS, and Azure Key Vault are supported.
-`incremental_location`<a name="incr-location"></a> | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Create an incremental backup in a different location than the default incremental backup location. <br><br>`WITH incremental_location = 'explicit_incrementals_URI'`<br><br>See [Incremental backups with explicitly specified destinations]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups-with-explicitly-specified-destinations) for usage.
-`STRICT`<a name="strict"></a> | [`BOOL`]({% link {{ page.version.version }}/bool.md %}) / None | A locality-aware backup running in `STRICT` mode fails if it cannot back up data from a node with a locality tag to a bucket with a matching locality tag.
+`STRICT`<a name="strict"></a> | [`BOOL`]({% link {{ page.version.version }}/bool.md %}) / None | A locality-aware backup running in `STRICT` mode fails if it cannot back up data from a node with a locality tag to a bucket with a matching locality tag.

src/current/_includes/v26.2/backups/locality-aware-backups.md

@@ -1,7 +1,3 @@
-{{site.data.alerts.callout_info}}
-`SHOW BACKUP` is able to display metadata using `check_files` for locality-aware backups taken with the [`incremental_location`]({% link {{ page.version.version }}/show-backup.md %}#show-a-backup-taken-with-the-incremental-location-option) option.
-{{site.data.alerts.end}}
-
 To view a list of [locality-aware backups]({% link {{ page.version.version }}/take-and-restore-locality-aware-backups.md %}), pass the endpoint [collection URI]({% link {{ page.version.version }}/backup.md %}#backup-file-urls) that is set as the `default` location with `COCKROACH_LOCALITY=default`: 
 
 {% include_cached copy-clipboard.html %}

src/current/_includes/v26.2/misc/session-vars.md

@@ -99,6 +99,7 @@
 | <a id="transaction-status"></a> `transaction_status` | The state of the current transaction. See [Transactions]({% link {{ page.version.version }}/transactions.md %}) for more details. | `NoTxn` | No | Yes |
 | <a id="transaction-timeout"></a> `transaction_timeout` | Aborts an explicit [transaction]({% link {{ page.version.version }}/transactions.md %}) when it runs longer than the configured duration. Stored in milliseconds; can be expressed in milliseconds or as an [`INTERVAL`]({% link {{ page.version.version }}/interval.md %}). | `0` | Yes | Yes |
 | <a id="troubleshooting_mode_enabled"></a> `troubleshooting_mode_enabled` | When enabled, avoid performing additional work on queries, such as collecting and emitting telemetry data. This session variable is particularly useful when the cluster is experiencing issues, unavailability, or failure. | `off` | Yes | Yes |
+| <a id="use-backups-with-ids"></a> `use_backups_with_ids` | Enable backup ID-based interface for [`SHOW BACKUPS`]({% link {{ page.version.version }}/show-backup.md %}) with time filtering and [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) operations. When enabled, backups are identified by unique IDs rather than timestamps, and you can use `NEWER THAN` and `OLDER THAN` clauses for server-side time filtering. Also controls whether `LATEST` uses new or legacy resolution. | `off` | Yes | Yes |
 | <a id="use_declarative_schema_changer"></a> `use_declarative_schema_changer` | Whether to use the declarative schema changer for supported statements. | `on` | Yes | Yes |
 | <a id="vector-search-beam-size"></a> `vector_search_beam_size` | The size of the vector search beam, which determines how many vector partitions are considered during query execution. For details, refer to [Tune vector indexes]({% link {{ page.version.version }}/vector-indexes.md %}#tune-vector-indexes). | `32` | Yes | Yes |
 | <a id="vectorize"></a> `vectorize` | The vectorized execution engine mode. Options include `on` and `off`. For more details, see [Configure vectorized execution for CockroachDB]({% link {{ page.version.version }}/vectorized-execution.md %}#configure-vectorized-execution). | `on` | Yes | Yes |

src/current/v26.2/alter-backup-schedule.md

@@ -155,23 +155,21 @@ Full backups are implicitly of `backup_type` `0`, and so does not display in the
 
 ### Apply different options to scheduled backups
 
-{% include common/sql/incremental-location-warning.md %}
-
 You can modify the behavior of your backup schedule and the backup jobs with `SET SCHEDULE OPTION` and `SET WITH`. See the [Schedule options](#schedule-options) table and the [Backup options](#backup-options) table for a list of the available options.
 
-This statement changes the default `wait` value for the `on_previous_running` schedule option to `start`. If a previous backup started by the schedule is still running, the scheduled job will now start the new backup anyway, rather than waiting. The backup option [`incremental_location`]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups-with-explicitly-specified-destinations) modifies the storage location for incremental backups:
+This statement changes the default `wait` value for the `on_previous_running` schedule option to `start`. If a previous backup started by the schedule is still running, the scheduled job will now start the new backup anyway, rather than waiting. It also adds the `revision_history` backup option:
 
 ~~~sql
-ALTER BACKUP SCHEDULE 814168045421199361 SET SCHEDULE OPTION on_previous_running = 'start', SET WITH incremental_location = 'external://gcs_incremental_storage';
+ALTER BACKUP SCHEDULE 814168045421199361 SET SCHEDULE OPTION on_previous_running = 'start', SET WITH revision_history;
 ~~~
 
-The incremental backup schedule's `BACKUP` statement shows that it will read files in the full backup location `'external://gcs_storage'` and ultimately store the incremental backup in `'external://gcs_incremental_storage'` on an hourly basis:
+The incremental backup schedule's `BACKUP` statement now includes revision history:
 
 ~~~
-     schedule_id     |    label    | status |       first_run        | schedule |                                                        backup_stmt
----------------------+-------------+--------+------------------------+----------+----------------------------------------------------------------------------------------------------------------------------
-  814168045421199361 | gcs_backups | ACTIVE | 2022-11-15 21:00:00+00 | @hourly  | BACKUP INTO LATEST IN 'external://gcs_storage' WITH detached, incremental_location = 'external://gcs_incremental_storage'
-  814155335856521217 | gcs_backups | ACTIVE | 2022-11-16 00:00:00+00 | @daily   | BACKUP INTO 'external://gcs_storage' WITH detached, incremental_location = 'external://gcs_incremental_storage'
+     schedule_id     |    label    | status |       first_run        | schedule |                                                  backup_stmt
+---------------------+-------------+--------+------------------------+----------+----------------------------------------------------------------------------------------------------------------
+  814168045421199361 | gcs_backups | ACTIVE | 2022-11-15 21:00:00+00 | @hourly  | BACKUP INTO LATEST IN 'external://gcs_storage' WITH detached, revision_history
+  814155335856521217 | gcs_backups | ACTIVE | 2022-11-16 00:00:00+00 | @daily   | BACKUP INTO 'external://gcs_storage' WITH detached, revision_history
 (2 rows)
 ~~~
 

src/current/v26.2/backup-and-restore-overview.md

@@ -8,7 +8,6 @@ docs_area: manage
 CockroachDB is built to be [fault-tolerant with automatic recovery]({% link {{ page.version.version }}/demo-cockroachdb-resilience.md %}), but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB {{ site.data.products.core }} clusters provide a range of [backup and restore features](#backup-and-restore-support).
 
 - [Backup and restore support](#backup-and-restore-support)
-  - [Additional backup and restore features](#additional-backup-and-restore-features)
 - [Scheduled backups](#scheduled-backups)
 - [Backup jobs with locality requirements](#backup-jobs-with-locality-requirements)
 - [Backup and restore SQL statements](#backup-and-restore-sql-statements)
@@ -84,11 +83,6 @@ This table outlines the level of product support for backup and restore features
   </tbody>
 </table>
 
-### Additional backup and restore features
-
-- [Incremental backups with explicitly specified destinations]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups-with-explicitly-specified-destinations)
-- [Exclude a table's data from backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#exclude-a-tables-data-from-backups)
-
 ## Scheduled backups
 
 {% include {{ page.version.version }}/backups/scheduled-backups-tip.md %}
@@ -162,5 +156,6 @@ For practical examples of running backup and restore jobs, watch the following v
 ## See also
 
 - Considerations for using [backup]({% link {{ page.version.version }}/backup.md %}#considerations) and [restore]({% link {{ page.version.version }}/restore.md %}#considerations).
+- [Exclude a table's data from backups]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#exclude-a-tables-data-from-backups)
 - [Backup collections]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#backup-collections) for details on how CockroachDB stores backups.
 - [Restoring backups]({% link {{ page.version.version }}/restoring-backups-across-versions.md %}) across major versions of CockroachDB.