Update the description of incremental backups with locality aware #19398
Conversation
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
@kev-cao I applied the proposed changes to v24.3 + v25.1 with the removal of the old syntax — is that correct? Or, does the change need to apply to other versions? |
| @@ -130,7 +130,7 @@ To restore from a specific backup, use [`RESTORE FROM {subdirectory} IN ...`]({% | |||
|
|
|||
| ## Create an incremental locality-aware backup | |||
|
|
|||
| If you backup to a destination already containing a [full backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups), an [incremental backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups) will be appended to the full backup in a subdirectory. When you're taking an incremental backup, you must ensure that the incremental backup localities match the full backup localities otherwise you will receive an error. Alternatively, take another full backup with the matching localities before running the incremental backup. | |||
| If you back up to a destination already containing a [full backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups), an [incremental backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups) will be appended to the full backup in a subdirectory. To take a locality-aware incremental backup and restore from it successfully, you must maintain the same storage URI and `COCKROACH_LOCALITY` mappings that were established by the corresponding full backup. Alternatively, take another full backup with the matching localities and URIs before running the incremental backup. | |||
There was a problem hiding this comment.
I think there was some confusion/ambiguity with my answer in Slack. The incremental mappings don't have to match the full backup mappings, they just have to be consistent. So if with one BACKUP command you have incremental_location = ('foo?region=us-east', 'bar?region=us-west', 'baz?region=us-central'), then that mapping must be maintained for all incrementals in that chain. @dt if you could confirm this behavior that'd be helpful!
There was a problem hiding this comment.
Hey @kev-cao, are you only to referring to incremental_location in your comment here? Or, all incrementals? I haven't changed the text for the incremental_location option on this page. This update is only referring to regular incrementals — so I want to check whether I need to adjust the edits I've made or not.
| @@ -130,7 +130,7 @@ To restore from a specific backup, use [`RESTORE FROM {subdirectory} IN ...`]({% | |||
|
|
|||
| ## Create an incremental locality-aware backup | |||
|
|
|||
| If you backup to a destination already containing a [full backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups), an [incremental backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups) will be appended to the full backup in a subdirectory. When you're taking an incremental backup, you must ensure that the incremental backup localities match the full backup localities otherwise you will receive an error. Alternatively, take another full backup with the matching localities before running the incremental backup. | |||
| If you back up to a destination already containing a [full backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#full-backups), an [incremental backup]({% link {{ page.version.version }}/take-full-and-incremental-backups.md %}#incremental-backups) will be appended to the full backup in a subdirectory. To take a locality-aware incremental backup and restore from it successfully, you must maintain the same storage URI to `COCKROACH_LOCALITY` parameter mappings for all incrementals in the backup collection. Alternatively, take another full backup with the necessary storage URI to `COCKROACH_LOCALITY` mapping before running an incremental backup. | |||
There was a problem hiding this comment.
a tiny thing, but i had to look up that COCKROACH_LOCALITY is a query parameter to the backup URI. Suggest editing slightly to "... to COCKROACH_LOCALITY query parameter mappings ..."
katmayb
force-pushed
the
locality-aware-uri-map
branch
from
f693140 to
1f7bb30
Compare
|
TFTRs! |
Fixes DOC-12344
Adjust the sentence in v24.3 + v25.1 regarding locality-aware incremental backups to clarify that the the storage URI + the
COCKROACH_LOCALITYregion must match the related full backup.