InfluxDB 3: standardized CLI params and env vars (companion to influxdb_pro#4708)#7549
InfluxDB 3: standardized CLI params and env vars (companion to influxdb_pro#4708)#7549reidkaufmann wants to merge 15 commits into
Conversation
…ames - Rename flags: wal-files-per-snapshot, wal-max-buffered-writes, query-log-max-entries, exec-mem-pool-size, file-cache-size, file-cache-recency, disable-data-file-cache, wait-for-running-ingester (legacy names noted as deprecated aliases) - De-prefix INFLUXDB3_ENTERPRISE_* environment variables to INFLUXDB3_* with legacy names as deprecated aliases - Rename #4237 env vars: DISABLE_TELEMETRY_UPLOAD, WITHOUT_AUTH, NODE_ID, DATA_DIR, SNAPSHOTTED_WAL_FILES_TO_KEEP - Document size-value parsing rules and megabyte-to-byte transition - Document file-cache-size 50/50 budget split during migration - Document max-http-request-size unit-suffix support - Fix TCP listener env var spelling and document conn-info env var
- Rename all --pt-* preview flags to their unprefixed names (no backward compatibility: old flags error, old envs ignored) - Note collapses into shared engine-agnostic options: wal-flush-interval, replication-interval, file-cache-size, file-cache-recency, disable-data-file-cache - Rename --pt-wal-max-buffer-size to --wal-buffer-size, --pt-wal-replica-queue-size to --wal-replica-queue-length, --pt-max-columns to --max-total-columns, --pt-gen0-max-bytes-per-file to --gen0-max-file-size, *-target-bytes to *-target-size - INFLUXDB3_ENTERPRISE_USE_PACHA_TREE renamed to INFLUXDB3_USE_PACHA_TREE (legacy name aliased)
- Rename flag rows and anchors: disable-data-file-cache, exec-mem-pool-size, file-cache-recency, file-cache-size, query-log-max-entries, wal-max-buffered-writes, wal-files-per-snapshot, wait-for-running-ingester, disable-telemetry-upload - Replace removed --pt-* row with pointer to preview configuration - Update quick-start examples to INFLUXDB3_NODE_ID
- INFLUXDB3_LICENSE_* (license, tokens, upgrade, setup pages) with deprecation note for legacy INFLUXDB3_ENTERPRISE_* names - INFLUXDB3_CLUSTER_ID, INFLUXDB3_NODE_ID, INFLUXDB3_MODE, INFLUXDB3_DATA_DIR, INFLUXDB3_DISABLE_TELEMETRY_UPLOAD - exec-mem-pool-size, file-cache-size, wal-files-per-snapshot renames in clustering, performance-tuning, durability, and troubleshoot pages - Replace bare megabyte cache values with explicit unit suffixes
…tup warning - INFLUXDB3_NODE_IDENTIFIER_FROM_ENV renamed to INFLUXDB3_NODE_ID_FROM_ENV (legacy name aliased with deprecation warning) - Note startup warning for INFLUXDB3_PT_* / INFLUXDB3_ENTERPRISE_PT_* environment variables that are still set
- config-options: tables for aliased renames (options+envs, env-only, and the Enterprise ENTERPRISE_-prefix drop) derived from the ENV_ALIASES and ENT_ENV_ALIASES tables in the code - performance-preview/configure: complete pt- to new-name table (no aliases) with pointers to shared engine-agnostic options
Vale Style Check Results
Warnings (23)
Showing first 20 of 23 warnings. ✅ Check passed |
🔗 Link Check Results — Link Check Bot✅ All links are valid
|
| Source File | URL | Issue |
|---|---|---|
content/influxdb3/core/admin/backup-restore/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/backup-restore/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/admin/performance-tuning/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/admin/performance-tuning/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/performance-tuning/_index.md |
file:///home/runner/work/docs-v2/docs-v2/public/influxdb3/core/admin/monitor-metrics | File not found. Check if file exists and path is correct: File not found. Check … |
content/influxdb3/core/admin/tokens/admin/preconfigured/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/admin/tokens/admin/preconfigured/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/core/object-storage/minio/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/object-storage/minio/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/reference/cli/influxdb3/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/core/reference/cli/influxdb3/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/core/reference/cli/influxdb3/serve/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/core/reference/cli/influxdb3/serve/_index.md |
https://reddit.com/r/influxdb | 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/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/backup-restore/_index.md |
https://support.influxdata.com/ | Error (cached): Error (cached) |
content/influxdb3/enterprise/admin/clustering/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
content/influxdb3/enterprise/admin/clustering/_index.md |
https://support.influxdata.com/ | Network error: SSL certificate not trusted. Use --insecure if site is trusted (e… |
content/influxdb3/enterprise/admin/delete-data/_index.md |
https://reddit.com/r/influxdb | Error (cached) |
Showing first 20 of 68 warnings. See the workflow run for full results.
Full details: workflow run summary and artifact. Last updated: 2026-07-23 21:44:52 UTC
jstirnaman
added
release:pending
Add explicit id anchors for datafusion-config, http-bind, max-http-request-size, object-store-connection-limit, object-store-http2-only, and object-store-max-retries rows so inbound fragment links (from performance-tuning and external deep links) resolve. Also rename the disable-data-file-cache and use-pacha-tree rows.
…-tree - Document --upgrade-pacha-tree (INFLUXDB3_UPGRADE_PACHA_TREE) as the storage engine upgrade trigger; mark --use-pacha-tree and its env vars deprecated - Rework performance-preview pages: PachaTree is the default engine for new clusters; Parquet applies to clusters that started on 3.10 or earlier that have not run the storage engine upgrade; drop --use-pacha-tree from examples; add auto-dvc options; update final-compaction-age default - Rename --disable-data-file-cache to --disable-file-cache (canonical in Core and Enterprise; disable-parquet-mem-cache and disable-data-file-cache as aliases; env INFLUXDB3_DISABLE_FILE_CACHE) - Note help curation: Parquet-only tuning flags hidden from default --help but functional; num-*-limit flags warn when set on PachaTree; --max-total-columns is the PachaTree counterpart of --num-total-columns-per-table-limit - Document PachaTree thread/core semantics: both runtimes default to the licensed core count; io+datafusion sum check applies to Parquet only; home license forces 1+1 - Update storage-engine gating wording on loadcap, import, delete-data, backup-restore, and upgrade pages - Move TCP_LISTINER alias row to the shared migration table (now aliased in Core and Enterprise) - Fix migrate-from-pt-option-names link fragment
…d crash-recovery runbook - Rewrite influxdb3 stop node to the two-phase contract (stopping -> drain WAL tail -> stopped): the command now waits for stopped by default (--timeout, default 5m; --no-wait to skip; non-zero exit on timeout) and must be run against the live node. Remove the kill-first example and the clean-up-after-kill framing. - Add influxdb3 remove node reference (new remove command section): removal requires a stopped node; --force-finalize documented as DATA-LOSS-UNSAFE; the 3.11 unsnapshotted-WAL removal refusal (HTTP 409) documented as PachaTree-mode-only, with Parquet and migrating clusters explicitly not guarded. - Add the engine-agnostic crash-recovery runbook at enterprise/admin/recover-node: restart with the same --node-id, stop gracefully to drain the tail, then remove; --force-finalize as last resort. Note that bare SIGTERM does not force a PachaTree snapshot. - Cross-link stop node, remove node, and the runbook; update the CLI command index and stop descriptions
|
Heads-up: this PR now carries one commit of tangential content — @cannonpalms could you review just that one commit (diff) for lifecycle-semantics accuracy? Wording was verified against the merged influxdata/influxdb_pro#4526 / influxdata/influxdb_pro#4706 help text and the #4720 guard implementation. |
|
@peterbarnett03 Question on scope: your recent help-text commits on influxdata/influxdb_pro#4708 de-brand the engine language ("the upgraded storage engine" / "run the storage engine upgrade" instead of PachaTree/Parquet). Should that carry into the public docs here? This branch currently leans the other way — it adds ~100 lines naming PachaTree across 24 files, including gating notes like "requires the PachaTree storage engine — the default for new clusters." If yes, note two practical bounds: (1) identifiers keep the name regardless — Also flagging one precision case for your call: the node-lifecycle pages ( |
|
Closed/re-opened to retrigger actions/workflows... it didn't work. I think the dead links are fixed though. |
…gine" Mirror the influxdb_pro #4708 help-text vocabulary on every page this PR touches, including pre-existing prose on those pages: - "the PachaTree storage engine" -> "the upgraded storage engine", with "the default for new clusters" attached at first mention per page - "Parquet-to-PachaTree migration" -> "the storage engine upgrade"; migrating clusters -> "mid-upgrade" (ParquetAndPachaTree enum no longer surfaced) - Parquet remains nameable; all identifiers unchanged (--upgrade-pacha-tree, --use-pacha-tree, INFLUXDB3_*PACHA* env vars, pt-/PT_ names in migration tables, quoted 409 and startup-warning text) - One parenthetical "(PachaTree)" kept in the config reference where the pt-/INFLUXDB3_PT_* identifiers are explained - Reword removal-guard scope with precision: guard applies to clusters that have fully adopted the upgraded engine; Parquet and mid-upgrade clusters are not guarded
|
@peterbarnett03 I went ahead and mirrored the de-branding — Two deliberate exceptions: one parenthetical "(PachaTree)" in the config reference anchoring what |
…am-env-cleanup # Conflicts: # content/influxdb3/enterprise/admin/clustering.md # content/influxdb3/enterprise/performance-preview/configure.md
There was a problem hiding this comment.
Pull request overview
Standardizes InfluxDB 3 CLI options and environment variables while documenting storage-engine migration and node lifecycle behavior.
Changes:
- Replaces deprecated option and environment-variable names and documents aliases.
- Updates upgraded-storage-engine configuration and migration guidance.
- Adds graceful node stopping, removal, and recovery documentation.
Reviewed changes
Copilot reviewed 40 out of 40 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
content/shared/influxdb3-write-guides/troubleshoot.md |
Updates memory-pool option names. |
content/shared/influxdb3-reference/telemetry.md |
Updates the telemetry environment variable. |
content/shared/influxdb3-internals-reference/durability.md |
Updates the memory-pool reference. |
content/shared/influxdb3-get-started/setup.md |
Updates node and licensing variables. |
content/shared/influxdb3-cli/stop/node.md |
Documents graceful node stopping. |
content/shared/influxdb3-cli/stop/_index.md |
Updates stop command behavior. |
content/shared/influxdb3-cli/remove/node.md |
Adds node-removal documentation. |
content/shared/influxdb3-cli/remove/_index.md |
Adds the remove command reference. |
content/shared/influxdb3-cli/config-options.md |
Documents standardized options, aliases, and sizes. |
content/shared/influxdb3-admin/upgrade.md |
Updates upgrade flags and licensing variables. |
content/shared/influxdb3-admin/upgrade-to-enterprise.md |
Updates Enterprise licensing examples. |
content/shared/influxdb3-admin/tokens/admin/preconfigured.md |
Updates the license email variable. |
content/shared/influxdb3-admin/performance-tuning.md |
Updates tuning options and defaults. |
content/shared/influxdb3-admin/object-storage/minio.md |
Updates cluster and node variables. |
content/shared/influxdb3-admin/backup-restore.md |
Updates storage-engine guidance. |
content/influxdb3/enterprise/reference/cli/influxdb3/stop/node.md |
Updates stop-node metadata and related links. |
content/influxdb3/enterprise/reference/cli/influxdb3/serve.md |
Updates the Enterprise serve reference. |
content/influxdb3/enterprise/reference/cli/influxdb3/remove/node.md |
Adds the remove-node page stub. |
content/influxdb3/enterprise/reference/cli/influxdb3/remove/_index.md |
Adds the remove section stub. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/start.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/preview.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/list.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/files.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/download.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/delete.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/loadcap/_index.md |
Updates storage-engine prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/import/_index.md |
Updates import prerequisites. |
content/influxdb3/enterprise/reference/cli/influxdb3/_index.md |
Adds remove and updates CLI summaries. |
content/influxdb3/enterprise/performance-preview/monitor.md |
Updates monitoring option names. |
content/influxdb3/enterprise/performance-preview/configure.md |
Documents renamed engine options and migration. |
content/influxdb3/enterprise/performance-preview/_index.md |
Updates storage-engine upgrade guidance. |
content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md |
Updates the license email variable. |
content/influxdb3/enterprise/admin/recover-node.md |
Adds crashed-node recovery guidance. |
content/influxdb3/enterprise/admin/load-capture.md |
Updates load-capture prerequisites. |
content/influxdb3/enterprise/admin/license.md |
Updates licensing environment variables. |
content/influxdb3/enterprise/admin/import-data.md |
Updates bulk-import prerequisites. |
content/influxdb3/enterprise/admin/delete-data.md |
Updates deletion prerequisites and flags. |
content/influxdb3/enterprise/admin/clustering.md |
Updates clustering configuration examples. |
content/influxdb3/core/reference/cli/influxdb3/serve.md |
Updates the Core serve reference. |
content/influxdb3/core/reference/cli/influxdb3/_index.md |
Updates the node ID variable example. |
Comments suppressed due to low confidence (5)
content/shared/influxdb3-admin/performance-tuning.md:146
- This example also places the server-only option before
serve, so the command is not valid. Move the option after the subcommand.
influxdb3 --exec-mem-pool-size=60% serve \
content/shared/influxdb3-admin/performance-tuning.md:155
--exec-mem-pool-sizemust follow theservesubcommand; only global options such as--num-io-threadsbelong before it. As written, this Enterprise example fails argument parsing.
influxdb3 --exec-mem-pool-size=90% serve \
content/shared/influxdb3-admin/performance-tuning.md:160
- This Enterprise example places a server option before the
servesubcommand, so it is not executable as written. Move the option afterserve.
influxdb3 --exec-mem-pool-size=60% serve \
content/shared/influxdb3-admin/performance-tuning.md:183
--file-cache-sizeis also aserveoption. Placing it before the subcommand makes this example invalid; the Core example above uses the correct ordering.
influxdb3 --file-cache-size=4GB serve \
content/influxdb3/enterprise/admin/license.md:381
- This assignment is not exported, so the separately invoked server does not receive
INFLUXDB3_LICENSE_FILE. Export it as the later commercial-license example does.
INFLUXDB3_LICENSE_FILE=/path/to/license-file.jwt
| | `--wal-replica-queue-length` | Length of the queue between WAL file fetching and replica buffer merging (previously `--pt-wal-replica-queue-size`). | `100` | | ||
| | `--wal-replica-recovery-tail-skip-limit` | Number of consecutive missing WAL files before stopping replica recovery. | `128` | | ||
| | `--replica-gen0-load-concurrency` | Limit on the number of Gen0 files loaded concurrently when the replica starts. | `16` | | ||
| | `--replica-max-buffer-size` | Maximum replica buffer size (bytes or %). Used by query nodes to store WAL files replicated from ingest nodes. | 50% of available memory, capped at 16GB | |
There was a problem hiding this comment.
Not applied — --replica-max-buffer-size is MemorySize (influxdb_pro clap_blocks/serve.rs:769), which accepts bare numbers as bytes; only the MemorySizeMb transition flags (exec-mem-pool-size, file-cache-size, force-snapshot-mem-threshold) reject them. Doc wording clarified in 66da728b8 to spell out the accepted formats.
There was a problem hiding this comment.
We may have intended to reject all bare size args, but apparently applied that for the MemorySizeMb flags only. Sticking with the current state of 3.11RC since I don't know if further corrections would be released at this point (though I would prefer to fix it for consistency).
| The `influxdb3 stop` command gracefully stops nodes in your | ||
| {{< product-name >}} cluster. |
| > [!Important] | ||
| > #### The upgraded storage engine is the default for new clusters | ||
| > The upgraded storage engine described on these pages is the default for | ||
| > new {{% product-name %}} clusters--no flag is required. |
There was a problem hiding this comment.
I think I (claude) should fix this and plan to shortly, but in case there is other work afoot to document Pacha going from beta to default let me know how to sequence it @jstirnaman
| > [!Important] | ||
| > #### The upgraded storage engine is the default for new clusters | ||
| > New {{% product-name %}} clusters default to the upgraded storage | ||
| > engine--no flag is required. |
| > [!Important] | ||
| > #### The upgraded storage engine is the default for new clusters | ||
| > The upgraded storage engine described on these pages is the default for | ||
| > new {{% product-name %}} clusters. |
cannonpalms
left a comment
cannonpalms
left a comment
There was a problem hiding this comment.
Thank you for doing this. Would you mind pulling the wording from the help text? We did away with terms like "data-loss-unsafe."
…p text Drop the "DATA-LOSS-UNSAFE" label, which the shipped help text does not use, in favor of its phrasing: force removal of a node that did not shut down cleanly can lose data (acked writes not captured in a snapshot); nothing is lost if the node had finished snapshotting and only failed to report a clean stop. Loss risk remains explicit on every mention.
- performance-tuning: move serve-specific options (--exec-mem-pool-size, --file-cache-size, --wal-flush-interval) after the serve subcommand in examples; only --num-io-threads is a global option - license: export the license environment variables in examples so the serve process inherits them - config-options: list all deprecated wait-for-running env aliases in the per-option table, matching the migration tables - stop CLI index wrapper: update stale catalog-cleanup description - configure: spell out --replica-max-buffer-size value formats (bare number is bytes; unit suffixes and percentages accepted)
… storage engine - Retitle the section trio: "Storage engine upgrade" (landing), "Configure the upgraded storage engine", "Monitor the upgraded storage engine"; update seotitles and descriptions to match the de-branded page bodies - Rename the section menu entry to "Storage engine upgrade" and update the child pages' parent keys - Drop the beta and preview tags, which mislabel the now-default engine - Update the two name-based references outside the trio (clustering, performance-tuning) URLs, file paths, and slugs are unchanged (/performance-preview/ stays); renaming them remains a separate decision.
|
@jstirnaman Can I leave this PR to you to review and merge when 3.11 releases? |
Match the influxdb_pro parser change (PR #4763): all size-typed options reject bare numbers and require a unit suffix (b/kb/mb/gb/tb, case-insensitive), plus a percentage of total memory where supported. - Collapse the transitional megabyte-to-byte callout into the general size-value rule - Update max-http-request-size to units-required with default 10mb - Update replica-max-buffer-size value-format wording - Count-based options (bare integers) are unchanged
@reidkaufmann @cannonpalms Thanks for the explanation and review! |
Documentation for the CLI parameter / environment-variable standardization shipping in the next InfluxDB 3 release (influxdata/influxdb_pro#4708 — closes influxdata/influxdb_pro#4237, #4238).
Draft until the code PR merges — review-time changes to the code are expected to ripple here.
What's covered
INFLUXDB3_ENTERPRISE_*env vars de-prefixed with aliases; new Size option values section (bare number = bytes; unit suffixes; the transitional bare-number rejection on the four legacy-MB options)pt-prefix removed from every option (no back-compat — old flags error, old env vars log a startup warning); breaking-change callout; the five engine-collapsed flags; Migrate from pt- option names table (43 rows)exec-mem-pool20%,force-snapshot-mem-threshold50%), bare-MB example values converted to explicit units--file-cache-sizedocumented as a total budget with the 50/50 migration-mode splitHistorical release notes intentionally left on old names. RC release notes not included (written at release).
Checks: hugo build clean; lefthook pre-commit hooks pass; Vale left to CI.