influxdata / influxdata/docs-v2
docs(influxdb3): catalog v3 migration guide (3.10+) — open technical questions
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Goal
Author the deferred (post-GA / "week 1") deep-dive guide for the one-way
InfluxDB 3.10 catalog v3 migration. GA-day coverage already shipped: the
one-way-migration `[!Warning]` in `upgrade.md` plus the v3.10.0 release-notes
breaking-change entry. This guide is the **procedure** those alerts point
operators toward — not a duplicate.
The catalog v3 format only exists in **3.10 and later**, so the page is marked
`metadata: [v3.10+]`.
## Planned structure
- **Standalone** shared guide (page granularity / SEO), **based on `master`** as
an independent PR — no dependency on the GA stack.
- `content/shared/influxdb3-admin/catalog-v3-migration.md` (body)
- `content/influxdb3/core/admin/catalog-v3-migration.md` (stub)
- `content/influxdb3/enterprise/admin/catalog-v3-migration.md` (stub)
- Applies to **Core + Enterprise** (3.10 single-binary). Not clustered.
Enterprise-only `.pt` file-format-v2 content gated with `{{% show-in "enterprise" %}}`.
- Frontmatter: `metadata: [v3.10+]`, `weight: 206` (after `upgrade.md`),
`source:` shared file, cross-edition `alt_links`, `related:` →
`upgrade/`, `backup-restore/`, `release-notes/`.
## Content seed (authoritative — from v3.10.0 release notes)
- 3.10 **automatically migrates the on-disk catalog to v3 on first startup**.
- v3 catalog = **compact binary record format, ~5–6× smaller than v2**.
- Migration is **automatic, idempotent, and crash-safe**.
- **One-way**: 3.9.x binaries cannot read a v3 catalog.
- **Back up `{prefix}/catalogs/` and `{prefix}/_catalog_checkpoint`** before upgrading.
- **`influxdb3 debug catalog`** (Core + Enterprise) — inspect catalog state
offline from object storage, no running server. Subcommands: `list`,
`snapshot`, `sequence`. Intended as the inspect/verify backbone.
- Enterprise-only: `.pt` file format v2 (storage engine upgrade) also unreadable
by 3.9.x.
## Open technical questions (blocking publish — not in release notes)
1. **Migration log strings** — exact startup log lines that indicate migration
start / success, for the "Migrate" and "Troubleshooting" sections.
2. **Rollback procedure** — precise steps to restore the backed-up catalog
objects and point a binary at the restored store. Constraints?
3. **Sanctioned backup step** — is `influxdb3 debug catalog snapshot` the
recommended pre-migration backup, or should the guide instruct a plain
object-store copy of `{prefix}/catalogs/` + `{prefix}/_catalog_checkpoint`?
## Cross-cutting constraints
- "PachaTree" never appears; `.pt` framed as "storage engine upgrade
(`--use-pacha-tree`)" and Enterprise-gated.
- Storage-engine content = opt-in / preview, never "GA".
## Follow-up (separate)
- One-line reciprocal link on PR #7349: point the `upgrade.md` 3.10 callout to
this guide once its URL is final.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read the v3.10.0 release notes and the existing upgrade.md callout first, then resolve the migration log, rollback, and sanctioned-backup questions. Create the shared guide at content/shared/influxdb3-admin/catalog-v3-migration.md with the Core and Enterprise stubs, frontmatter, and links described. Done means the procedure is publishable and the open technical questions are answered.
Written by the indexing model from the issue text.
Assessment
- Domain
- databases, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100