Added deprecation note for WITH incremental_location = 'explicit_incrementals_URI #20952
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Added deprecation note for WITH incremental_location = 'explicit_incrementals_URI
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
alicia-l2
reviewed
Nov 3, 2025
There was a problem hiding this comment.
https://deploy-preview-20952--cockroachdb-docs.netlify.app/docs/v25.4/take-full-and-incremental-backups#incremental-backups-with-explicitly-specified-destinations I think we also should add a warning to this page as well as this is the page which talks about how to set the custom incremental location. I'm wondering if we add that warning in red? or yellow?
| <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 ability to specify a custom incremental location using `WITH incremental_location = 'explicit_incrementals_URI'` is deprecated in versions 25.4 and later. If you create a backup chain with a custom `incremental_location`, ensure that all operations related to that backup chain always specify `incremental_location` (i.e. `SHOW`, `RESTORE`, `BACKUP INTO LATEST`). |
There was a problem hiding this comment.
Can we edit this to say "If you are working with backups that have been previously created with a custom incremental location"
Adjusted warning and added to more pages
msbutler
reviewed
Nov 4, 2025
| `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 ability to specify a custom incremental location using `WITH incremental_location = 'explicit_incrementals_URI'` is deprecated in versions 25.4 and later. If you work with backups that were previously created with a custom `incremental_location`, ensure that all operations related to that backup chain always specify `incremental_location` (i.e. `SHOW`, `RESTORE`, `BACKUP INTO LATEST`). |
There was a problem hiding this comment.
If you work with backups that were previously created with a custom
incremental_location, ensure that all operations related to that backup chain always specifyincremental_location(i.e.SHOW,RESTORE,BACKUP INTO LATEST).
i'm a bit confused by this sentence. we want to advise users to stop using incremental_location, right?
There was a problem hiding this comment.
I was thinking that it was just the WITH incremental_location = 'explicit_incrementals_URI' statement that will no longer be valid, not incremental_location as a whole, but I'm not sure- @alicia-l2 can you clarify this at all?
There was a problem hiding this comment.
we want to encourage users to stop using the incremental_location parameter all together. And to clarify, this has always been an invalid statement
backup into ... with incremental_location
if the user used incremental_location they need to pass a value to the param. i.e.
backup into ... with incremental_location = 's3:///foo'
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes DOC-15327
Added deprecation note for WITH incremental_location = 'explicit_incrementals_URI