Skip to content

Added deprecation note for WITH incremental_location = 'explicit_incrementals_URI #20952

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Nov 14, 2025
Merged

Added deprecation note for WITH incremental_location = 'explicit_incrementals_URI #20952

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
df951e6
Added deprecation note
peachdawnleach Nov 3, 2025
7ab8c02
Adjusted warning and added to more pages
peachdawnleach Nov 4, 2025
ff9bc17
Merge branch 'main' into 20251103-doc-15327-deprecation-incremental
peachdawnleach Nov 4, 2025
342d92e
Added to more files
peachdawnleach Nov 6, 2025
6f70f5c
Moved to include
peachdawnleach Nov 7, 2025
0caec78
Merge branch 'main' into 20251103-doc-15327-deprecation-incremental
peachdawnleach Nov 7, 2025
f6ada16
Rewording
peachdawnleach Nov 14, 2025
1a99dab
Merge branch 'main' into 20251103-doc-15327-deprecation-incremental
peachdawnleach Nov 14, 2025
280b3e0
Broken link
peachdawnleach Nov 14, 2025
7eff910
Merge branch 'main' into 20251103-doc-15327-deprecation-incremental
peachdawnleach Nov 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/current/_includes/common/sql/incremental-location-warning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{{site.data.alerts.callout_danger}}
The `incremental_location` parameter is deprecated in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
Copy link
Contributor

@taroface taroface Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The precedent for deprecation notices is to be more vague, using the below wording (see style guide on this, though that part is about adding and not removing features). I would especially avoid citing v26.2 as the removal date could always change.

Suggested change
The `incremental_location` parameter is deprecated in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
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`.

Not sure if I understood the change correctly, though. Is there any guidance we can offer on how to achieve this functionality by other means? Ideally a deprecation notice also conveys how we want the user to adjust.

(Also note style correction to cited versions.)

Copy link
Contributor Author

@peachdawnleach peachdawnleach Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha, thanks for this- I'll check with @alicia-l2 and @msbutler to see if there's anything we want to add in terms of alternatives.

Copy link
Contributor Author

@peachdawnleach peachdawnleach Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From Michael- "There is no alternative way to achieve the same functionality via cockroach sql. That being said, the only use case for this option that we know of is to set fine grain ttl policies on full vs incremental backups, which the user can already do via their storage provider. i don't think we need to mention this though. If a customer bugs out, they can reach out, and we'll give them the workaround"

{{site.data.alerts.end}}
2 changes: 1 addition & 1 deletion src/current/_includes/v23.1/backups/backup-options-for-schedules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
`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.
<span class="version-tag">New in v23.1:</span> `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.
`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 in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
2 changes: 1 addition & 1 deletion src/current/_includes/v23.2/backups/backup-options-for-schedules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
`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.
`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 in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
2 changes: 1 addition & 1 deletion src/current/_includes/v24.1/backups/backup-options-for-schedules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
`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.
`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 in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
2 changes: 1 addition & 1 deletion src/current/_includes/v24.3/backups/backup-options-for-schedules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
`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.
`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 in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
2 changes: 1 addition & 1 deletion src/current/_includes/v25.2/backups/backup-options-for-schedules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@
`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.
`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 in versions 25.4 and later. If needed, you can continue to work with already existing backups that use a custom `incremental_location` , but this ability will be removed in version 26.2.
Loading
Loading