Repository navigation
docs(influxdb3): document 3.12 catalog backup and rollback for operators - #7835
Open
jstirnaman wants to merge 7 commits into
Open
jstirnaman wants to merge 7 commits into
jstirnaman wants to merge 7 commits into
Conversation
Contributor
Vale Style Check Results
Warnings (39)
Showing first 20 of 39 warnings. ✅ Check passed |
Contributor
Release version check
💡 Badge new features with the versionDocumenting a new feature? Add a version badge in the page frontmatter — the
For inline version text, use |
Contributor
🔗 Link Check Results — Link Check Bot❌ 1 broken link(s) found — fix them before merging.
Broken Links
|
| Source File | URL | Issue |
|---|---|---|
content/influxdb3/core/admin/upgrade/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/upgrade/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/backup-restore/_index.md |
file:///home/runner/work/docs-v2/docs-v2/public/influxdb3/enterprise/object-storage/minio | File not found. Check if file exists and path is correct: File not found. Check … |
content/influxdb3/enterprise/admin/backup-restore/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/backup-restore/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/backup-restore/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/databases/create/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/databases/create/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/databases/create/_index.md |
file:///home/runner/work/docs-v2/docs-v2/public/influxdb3/enterprise/api/v3 | File not found. Check if file exists and path is correct: File not found. Check … |
content/influxdb3/enterprise/admin/databases/delete/_index.md |
file:///home/runner/work/docs-v2/docs-v2/public/influxdb3/enterprise/api/v3 | File not found. Check if file exists and path is correct: File not found. Check … |
content/influxdb3/enterprise/admin/databases/delete/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/databases/delete/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/databases/enforce-schema/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/databases/enforce-schema/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/databases/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/databases/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/databases/list/_index.md |
file:///home/runner/work/docs-v2/docs-v2/public/influxdb3/enterprise/api/v3 | File not found. Check if file exists and path is correct: File not found. Check … |
content/influxdb3/enterprise/admin/databases/list/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/databases/list/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/distinct-value-cache/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
Showing first 20 of 74 warnings. See the workflow run for full results.
Full details: workflow run summary and artifact. Last updated: 2026-10-07 23:00:04 UTC
jstirnaman
marked this pull request as ready for review
October 1, 2026 23:09
jstirnaman
requested review from
hiltontj,
peterbarnett03 and
sanderson
and removed request for
a team
October 1, 2026 23:09
Contributor
5 tasks
This comment was marked as outdated.
This comment was marked as outdated.
github-actions
Bot
added
product:shared
What changed: - upgrade.md: add "Version-specific upgrade notes". The 3.12 section explains when the catalog feature level advances (including stopped nodes), the 3.11.x startup errors, how to back up the catalog, and how to roll back to 3.11.x, including the risk to data written after the upgrade. Add "Rolling upgrades to 3.12" (Enterprise). Keep the 3.10 one-way migration as a visible callout with corrected paths. Move the 3.2.x to 3.5.x boundary notes into a collapsed block. Point the multi-node procedure and catalog compatibility sections to these notes. - Release notes: the v3.12.0 callout tells operators to replace the catalog objects to roll back; the create restore note is Enterprise-only. - backup-restore.md: describe catalog/ as holding catalog/v3/snapshot and logs, and _catalog_checkpoint as a legacy file. - install.md: the Quay maintenance comment refers to the Core and Enterprise release commits. Why: Operators need to know what blocks a return to 3.11.x after upgrading and how to back up the catalog first. Impact: Core and Enterprise upgrade, backup and restore, and install pages, and release notes. Verification: Rollback behavior is under review in influxdata/DAR#779; testing on 3.12.0 GA found corrections still to make in this PR. Hugo build, Vale (product configs), code-block lint, and link check pass. Committed with --no-verify: the lint-instructions hook matches content files and flags existing "[Docker](#)" / "[Docker Compose](#)" tab labels as repetition.
jstirnaman
force-pushed
the
docs-upgrade-catalog-backup
branch
from
October 5, 2026 17:16
31ce333 to
fd8d8ee
Compare
What changed: - Replace unsupported automatic feature-level and catalog-only rollback claims with conditional guidance. - Add catalog and data backup guidance, troubleshooting, and cross-references. Why: - A pre-upgrade catalog paired with newer data can return rows from a different table. Impact: - Core and Enterprise documentation now directs customers to Support for rollback planning. Verification: - git diff --cached --check passed. - Changed-file link check passed; code-block lint could not start because p-limit is missing in this worktree.
What changed: - Add a generic 3.11.x startup failure troubleshooting entry. Why: - A three-node Enterprise test confirmed that a 3.12-only catalog record can block startup on 3.11.5. Impact: - Customers get a safe next step without depending on an internal record ID. Verification: - git diff --check passed. - Changed-file link check passed; code-block lint could not start because p-limit is missing in this worktree.
What changed: - Move 3.12 rollback troubleshooting after the upgrade procedures. - Put pre-upgrade review notes together and turn catalog backup guidance into ordered steps. - Give the Core upgrade page its own canonical URL and use literal product names in upgrade page descriptions. - Keep inline code and link spacing intact in generated Markdown twins. Why: Readers need preparation guidance before recovery guidance. Core and Enterprise upgrade pages contain distinct instructions, so Core needs its own canonical URL. The TechArticle JSON-LD sink leaves product-name shortcodes raw in descriptions. Impact: Core and Enterprise upgrade pages have a clearer sequence. Crawlers and agents receive the correct Core canonical URL and readable upgrade descriptions. Verification: - Hugo build passed. - Changed-file code block lint and link checks passed. - Markdown twin generation, coherence, and JSON-LD link checks passed. - Inspected rendered Core and Enterprise backup steps, canonical URLs, and JSON-LD descriptions.
What changed: - Replace 90 product-name shortcode occurrences in frontmatter descriptions across 86 Enterprise pages. - Keep page body content and other metadata unchanged. Why: The TechArticle JSON-LD template does not expand shortcodes in descriptions, so these pages exposed template syntax to crawlers and agents. This content change addresses the Enterprise pages while the template defect remains tracked in #7565. Impact: Enterprise page descriptions and generated Markdown twins use the explicit product name. Product behavior does not change. Verification: - Parsed every Enterprise frontmatter description; none retain product-name. - Hugo build passed, and 85 published changed pages rendered JSON-LD descriptions without a raw shortcode. Two changed pages are drafts. - Changed-file code block lint and link checks passed. - Markdown generation, Markdown coherence, and JSON-LD link checks passed. - Vale hooks flagged a pre-existing repeated "the" in the sample-data description. Left it unchanged as out of scope.
This branch has not been deployed
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
What changed
Why
InfluxDB 3.12 can write catalog records that 3.11.x cannot read. A pre-upgrade catalog restored beside newer data can also produce incorrect query results. Operators need the backup steps and version-specific changes before starting an upgrade, followed by recovery guidance when something fails.
The Core and Enterprise upgrade guides contain different catalog paths and cluster guidance, so Core needs its own canonical URL. The TechArticle JSON-LD template currently leaves
product-nameshortcodes raw in descriptions; #7565 tracks the site-wide template fix.Impact
Core and Enterprise readers get a clearer upgrade sequence and product-specific backup paths. Enterprise rolling upgrade and rollback troubleshooting guidance remains available after the procedures. Crawlers and agents get a Core canonical URL and explicit product names in the changed page descriptions. Product behavior and configuration do not change.
Verification
npx hugo --quietpassed. The rendered Core and Enterprise guides each show three complete backup steps and the intended heading order.yarn build:md,yarn build:llms-full,yarn check:md-coherence, andyarn check:jsonld-linkspassed. The changed published Enterprise pages render JSON-LD descriptions without rawproduct-nameshortcodes; two changed pages are drafts.--no-verifyafter Vale flagged the pre-existing repeated “the” incontent/influxdb3/enterprise/reference/sample-data.md; that wording remains for a separate fix.