v26.2 previews of faster `restore`, improved `show backups`; syntax updates/removals by mikeCRL · Pull Request #23215 · cockroachdb/docs

mikeCRL · 2026-04-23T18:41:54Z

netlify · 2026-04-23T18:42:17Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`387dcad`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/69ebdd2aeef1c80008993708

netlify · 2026-04-23T18:42:17Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`387dcad`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/69ebdd2acc24940007af9842

netlify · 2026-04-23T18:44:07Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`387dcad`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/69ebdd2a537e870008b6443f
😎 Deploy Preview	https://deploy-preview-23215--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2026-04-23T18:47:10Z

Files changed:

src/current/_includes/common/sql/incremental-location-warning.md
src/current/_includes/v26.2/backups/advanced-examples-list.md:

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

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

src/current/v26.2/backup.md

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

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

src/current/v26.2/alter-backup-schedule.md
src/current/v26.2/backup-and-restore-overview.md
src/current/v26.2/backup.md
src/current/v26.2/create-schedule-for-backup.md
src/current/v26.2/manage-a-backup-schedule.md
src/current/v26.2/restore.md
src/current/v26.2/show-backup.md
src/current/v26.2/take-and-restore-locality-aware-backups.md
src/current/v26.2/take-full-and-incremental-backups.md

- Backup IDs with efficient querying (use_backups_with_ids session variable, NEWER THAN/OLDER THAN filtering) - Faster restore with WITH EXPERIMENTAL COPY option - Backup compactions for extended backup chains - Remove incremental_location option (breaking change) Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

…-backups

This session variable is already in main via PR #23200 and should not appear in this PR's diff. Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

- Remove broken references to deleted incremental_location section - Replace cluster settings anchor links with plain code text (backup.compaction.threshold, backup.index.read.enabled)

kev-cao · 2026-04-24T15:44:40Z

+
+### Combine with faster restore
+
+You can combine backup IDs with the `WITH EXPERIMENTAL COPY` option for maximum performance:


maximum performance

kev-cao

Overall looks good to me! The only required changes right now are fixing the backup IDs to be proper backup IDs instead of timestamps, and removing the revision_start_time column when WITH REVISION START TIME isn't specified.

I went through some of our test backups and found this that you could use for our examples:

         id        |      backup_time       |  revision_start_time
-------------------+------------------------+-------------------------
  Wnfqrp0BAAD4tw8= | 2026-04-21 07:21:35+00 | 2026-04-21 07:20:22+00
  clvprp0BAADQmww= | 2026-04-21 07:20:22+00 | 2026-04-21 07:16:26+00
  osDlrp0B         | 2026-04-21 07:16:26+00 | 1970-01-01 00:00:00+00

kev-cao · 2026-04-24T16:48:38Z

+
+The threshold is the backup chain length at which compaction triggers:
+- `0`: Disabled (default)
+- `4`: Compaction occurs when chain reaches length 4 (1 full + 3 incrementals)


I'm wondering if we should have stronger wording about setting it to 4. If a customer reads this, they may be tempted to start setting it to what they think would work for them. @msbutler what do you think?

+1. At first glance this read to me that 4 is the minimum value but it can be set higher as desired. If we want to keep the recommended value at 4, that should be emphasized.

@msbutler @kev-cao Do you want to just be explicit here and elsewhere that 'higher values are not recommended' and try to drop an earlier mention that this is a 'configurable' number, just to de-emphazie that point, without actually implying everywhere that it's not configurable? Maybe that's the balance?

LMK and I'll try to implement. Also wouldn't mind merging and iterating, if that is better, to help our team get things sorted for the release quickly.

Yeah I think having an explicit statement is fine

Replace timestamp-based IDs with real backup IDs from engineer's sample data: - Wnfqrp0BAAD4tw8= (newest) - clvprp0BAADQmww= (middle) - osDlrp0B (oldest) Updated all SHOW BACKUPS and RESTORE examples in show-backup.md and restore.md to use proper backup ID format instead of timestamps like '2026-04-16T14:23:55.335570Z'. Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

This reverts commit 908ffe8.

mikeCRL · 2026-04-24T17:31:03Z

Overall looks good to me! The only required changes right now are fixing the backup IDs to be proper backup IDs instead of timestamps, and removing the revision_start_time column when WITH REVISION START TIME isn't specified.

I went through some of our test backups and found this that you could use for our examples:
         id        |      backup_time       |  revision_start_time
-------------------+------------------------+-------------------------
  Wnfqrp0BAAD4tw8= | 2026-04-21 07:21:35+00 | 2026-04-21 07:20:22+00
  clvprp0BAADQmww= | 2026-04-21 07:20:22+00 | 2026-04-21 07:16:26+00
  osDlrp0B         | 2026-04-21 07:16:26+00 | 1970-01-01 00:00:00+00

@kev-cao FIxed! PTAL. I think all the necessary items are now resolved.

jhlodin

Left a few comments and suggestions

jhlodin · 2026-04-24T17:50:54Z

+
+The threshold is the backup chain length at which compaction triggers:
+- `0`: Disabled (default)
+- `4`: Compaction occurs when chain reaches length 4 (1 full + 3 incrementals)


+1. At first glance this read to me that 4 is the minimum value but it can be set higher as desired. If we want to keep the recommended value at 4, that should be emphasized.

jhlodin · 2026-04-24T17:51:58Z

+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| `backup.compaction.threshold` | Backup chain length at which compaction triggers. `0` disables; minimum `4`. | `0` |


As a suggestion - see above discussion

Same feedback applies to other files if eng determines this is the suggested approach

jhlodin · 2026-04-24T17:54:49Z

+
+### Prerequisites
+
+To run faster restores, [backup compactions]({% link {{ page.version.version }}/backup.md %}#backup-compactions) must be enabled on the backup you are restoring from. To enable compactions, set the `backup.compaction.threshold` cluster setting to `4` or higher before creating your backups.


This wording makes it sound like "faster restores" is a proper noun/feature name, rather than descriptive. Suggest "To optimize restore performance" as a more descriptive alternative

@jhlodin Since this restore method is distinct, it’s likely to read like a feature name, even while we intentionally avoid fully treating it like one. Eng/PM aligned on “faster restores,” and I’d prefer to stick with that to avoid it being misread as just a faster version of the traditional approach, which it isn’t. The Preview status also helps signal that it’s something different.

This is a temporary phase anyway; it’ll eventually become the default (details TBD). For now, we clarify that it refers to restores using WITH EXPERIMENTAL COPY, though that specific syntax likely won’t always be required.

The only alternative I’ve considered is a more-specific “Faster restores using WITH EXPERIMENTAL COPY,” but it’s a bit clunky, so I leaned on context instead. Open to other ideas, but hopefully that context helps explain the tradeoffs and the choice thus far?

Makes sense. If eng/PM aligned on the name already then I won't push back more now

kev-cao

LGTM!

msbutler

awesome work on this!

msbutler · 2026-04-24T19:37:23Z

+
+### Prerequisites
+
+To run faster restores, [backup compactions]({% link {{ page.version.version }}/backup.md %}#backup-compactions) must be enabled on the backup you are restoring from. To enable compactions, set the `backup.compaction.threshold` cluster setting to `4` or higher before creating your backups.


should we simply say; set the value to 4?

Sorry I missed this before. Refined.

msbutler · 2026-04-24T20:39:15Z

-
-| Setting | Description | Default |
-|---------|-------------|---------|
-| `backup.compaction.threshold` | Backup chain length at which compaction triggers. `0` disables. `4` is the only recommended value for compaction. | `0` |


we do need to keep backup.compaction.threshold cluster setting change doc, just not backup.index.read.enabled

@msbutler I dropped the table because we thoroughly covered backup.compaction.threshold nearby with the same details, so the section/table no longer seemed necessary. WDYT?

ah, then its fine to drop the table. ty!

msbutler

Thanks for doing this so quickly!

jhlodin

LGTM

mikeCRL force-pushed the DOC-16503_faster-show-backups branch 2 times, most recently from ecf873e to ee64899 Compare April 24, 2026 13:19

mikeCRL force-pushed the DOC-16503_faster-show-backups branch from 8e091fe to 7a54c9f Compare April 24, 2026 13:52

mikeCRL and others added 2 commits April 24, 2026 10:01

Merge remote-tracking branch 'origin/main' into DOC-16503_faster-show…

8d388ba

…-backups

Remove canary_stats_mode from session variables

908ffe8

This session variable is already in main via PR #23200 and should not appear in this PR's diff. Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

mikeCRL changed the title ~~v26.2 previews of faster restore, improved show backups; syntax deprecations/removals [DOC-16710] [DOC-16709] [DOC-16503]~~ v26.2 previews of faster restore, improved show backups; syntax deprecations/removals Apr 24, 2026

mikeCRL marked this pull request as ready for review April 24, 2026 14:04

mikeCRL requested a review from kev-cao April 24, 2026 14:04

mikeCRL added 2 commits April 24, 2026 10:13

Fix link

092431f

Fix broken links and remove cluster settings anchors

f18a31b

- Remove broken references to deleted incremental_location section - Replace cluster settings anchor links with plain code text (backup.compaction.threshold, backup.index.read.enabled)

mikeCRL mentioned this pull request Apr 24, 2026

Replace cockroach encode-uri with convert-url in v26.2 #23218

Merged

kev-cao requested changes Apr 24, 2026

View reviewed changes

Updates per review

d44cbd0

mikeCRL requested a review from kev-cao April 24, 2026 16:44

Additional edit from review

76b521c

kev-cao reviewed Apr 24, 2026

View reviewed changes

mikeCRL and others added 4 commits April 24, 2026 13:05

Improve backup id syntax in parameters table

235847e

Revert "Remove canary_stats_mode from session variables"

cd4e4df

This reverts commit 908ffe8.

Additional fix to drop revision timestamp

465f4a7

Merge branch 'main' into DOC-16503_faster-show-backups

605349a

mikeCRL requested a review from kev-cao April 24, 2026 17:33

mikeCRL changed the title ~~v26.2 previews of faster restore, improved show backups; syntax deprecations/removals~~ v26.2 previews of faster restore, improved show backups; syntax updates/removals Apr 24, 2026

jhlodin reviewed Apr 24, 2026

View reviewed changes

mikeCRL requested a review from jhlodin April 24, 2026 19:15

kev-cao approved these changes Apr 24, 2026

View reviewed changes

msbutler reviewed Apr 24, 2026

View reviewed changes

Comment thread src/current/v26.2/backup.md Outdated

msbutler reviewed Apr 24, 2026

View reviewed changes

mikeCRL added 2 commits April 24, 2026 16:30

Refine compaction threshold language

72c3098

More edits per review

62ef81b

mikeCRL requested a review from msbutler April 24, 2026 20:36

msbutler reviewed Apr 24, 2026

View reviewed changes

Additional minor tweaks from review

416564e

mikeCRL requested a review from msbutler April 24, 2026 20:45

msbutler approved these changes Apr 24, 2026

View reviewed changes

jhlodin approved these changes Apr 24, 2026

View reviewed changes

mikeCRL and others added 2 commits April 24, 2026 16:57

Fix link

9421c98

Merge branch 'main' into DOC-16503_faster-show-backups

387dcad

mikeCRL enabled auto-merge (squash) April 24, 2026 21:14

mikeCRL merged commit 1c9933a into main Apr 24, 2026
7 checks passed

mikeCRL deleted the DOC-16503_faster-show-backups branch April 24, 2026 21:22


		### Combine with faster restore

		You can combine backup IDs with the `WITH EXPERIMENTAL COPY` option for maximum performance:

	\| `backup.compaction.threshold` \| Backup chain length at which compaction triggers. `0` disables; minimum `4`. \| `0` \|
	\| `backup.compaction.threshold` \| Backup chain length at which compaction triggers. `0` disables; minimum and recommended value of `4`. \| `0` \|


		### Prerequisites

		To run faster restores, [backup compactions]({% link {{ page.version.version }}/backup.md %}#backup-compactions) must be enabled on the backup you are restoring from. To enable compactions, set the `backup.compaction.threshold` cluster setting to `4` or higher before creating your backups.

Conversation

mikeCRL commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

github-actions Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kev-cao left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikeCRL commented Apr 24, 2026

Uh oh!

jhlodin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kev-cao left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

msbutler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mikeCRL commented Apr 23, 2026 •

edited

Loading

netlify Bot commented Apr 23, 2026 •

edited

Loading

netlify Bot commented Apr 23, 2026 •

edited

Loading

netlify Bot commented Apr 23, 2026 •

edited

Loading

github-actions Bot commented Apr 23, 2026 •

edited

Loading