Configure the upgraded storage engine

This page provides a complete reference for the upgraded storage engine configuration options.

If an option is omitted, the server either derives a value from the existing influxdb3 serve configuration or falls back to an engine-specific default that balances resource usage and throughput.

Most of the options on this page are tuning options that do not appear in the default influxdb3 serve --help output; use --help-all to list them.

• General
• WAL
• Snapshot
• Gen0
• File cache
• Replication (query nodes)
• Compactor
• L1-L4 level tuning
• Example configurations
• Downgrade options
• Migrate from pt- option names

General

Engine path prefix

Use a short prefix to improve partitioning in object stores:

influxdb3 serve \
  # ...
  --engine-path-prefix mydata

Hybrid query mode

During and after the storage engine upgrade, hybrid query mode merges results across both Parquet and .pt files. Disable hybrid mode to query only .pt data:

influxdb3 serve \
  # ...
  --disable-hybrid-query

WAL

Configure Write-Ahead Log (WAL) behavior for durability and performance.

WAL buffer size

The WAL buffer accumulates incoming writes before flushing to object storage. Larger buffers reduce flush frequency and produce larger WAL files, but increase memory usage:

influxdb3 serve \
  # ...
  --wal-buffer-size 30MB

Flush interval and concurrency

Control how frequently the WAL flushes and how many workers run flushes in parallel:

influxdb3 serve \
  # ...
  --wal-flush-interval 2s \
  --wal-flush-concurrency 8

Snapshot

Configure snapshot buffer behavior, which controls how WAL files are merged into Gen0 files.

Snapshot size and duration

Control when snapshot rotation triggers:

influxdb3 serve \
  # ...
  --snapshot-size 500MB \
  --snapshot-duration 15s

Merge threshold

Set the size threshold that triggers background merge operations. Lower values result in more frequent merges:

influxdb3 serve \
  # ...
  --merge-threshold-size 125MB

Gen0

Control the size of Gen0 files produced during merge operations.

Gen0 file size limits

Control the size of Gen0 files for query and compaction performance:

influxdb3 serve \
  # ...
  --gen0-max-rows-per-file 5000000 \
  --gen0-max-file-size 50MB

File cache

Configure data file caching for query performance.

File cache size

Set the maximum size for the data file cache:

influxdb3 serve \
  # ...
  --file-cache-size 8GB

Cache recency filter

Only cache files containing data within a recent time window:

influxdb3 serve \
  # ...
  --file-cache-recency 24h

Disable caching on ingest nodes

For dedicated ingest nodes, disable the data file cache to save memory:

influxdb3 serve \
  # ...
  --mode ingest \
  --disable-file-cache

Replication (query nodes)

Configure replication behavior for query nodes in distributed deployments.

Recovery concurrency

Control parallelism during query node recovery or catchup:

influxdb3 serve \
  # ...
  --mode query \
  --wal-replica-recovery-concurrency 16

Steady-state replication

Configure ongoing replication performance:

influxdb3 serve \
  # ...
  --mode query \
  --wal-replica-steady-concurrency 4 \
  --wal-replica-queue-length 200

Replica buffer size

Control the maximum buffer size for replicated data on query nodes:

influxdb3 serve \
  # ...
  --mode query \
  --replica-max-buffer-size 8GB

Compactor

Configure background compaction behavior. The compactor organizes data into fixed 24-hour UTC windows and progresses data through four compaction levels (L1 through L4).

Compaction budget

Control total memory allocated to active compaction jobs:

influxdb3 serve \
  # ...
  --compactor-input-size-budget 8GB

Final compaction age

Control when windows receive their final compaction into L4:

influxdb3 serve \
  # ...
  --final-compaction-age 48h

L1-L4 level tuning

These options control per-level compaction parameters. Data enters L1 from snapshot batch compaction and promotes through levels based on run set count triggers.

L1 options

L2 options

L3 options

L4 options

Example configurations

Development (minimal resources)

influxdb3 serve \
  --node-id dev01 \
  --cluster-id dev-cluster \
  --object-store file \
  --data-dir ~/.influxdb3 \
  --num-io-threads 2 \
  --datafusion-num-threads 2 \
  --file-cache-size 512MB \
  --wal-buffer-size 5MB \
  --snapshot-size 100MB

Production all-in-one (8 cores, 32 GB RAM)

influxdb3 serve \
  --node-id prod01 \
  --cluster-id prod-cluster \
  --object-store s3 \
  --bucket S3_BUCKET \
  --aws-access-key-id AWS_ACCESS_KEY_ID \
  --aws-secret-access-key AWS_SECRET_ACCESS_KEY \
  --num-io-threads 5 \
  --datafusion-num-threads 3 \
  --file-cache-size 8GB \
  --wal-buffer-size 30MB \
  --snapshot-size 500MB \
  --wal-flush-concurrency 4

High-throughput ingest node (16 cores)

influxdb3 serve \
  --node-id ingest01 \
  --cluster-id prod-cluster \
  --object-store s3 \
  --bucket S3_BUCKET \
  --aws-access-key-id AWS_ACCESS_KEY_ID \
  --aws-secret-access-key AWS_SECRET_ACCESS_KEY \
  --mode ingest \
  --num-io-threads 12 \
  --datafusion-num-threads 4 \
  --wal-buffer-size 50MB \
  --wal-flush-interval 2s \
  --wal-flush-concurrency 8 \
  --snapshot-size 1GB \
  --disable-file-cache

Query-optimized node (16 cores)

influxdb3 serve \
  --node-id query01 \
  --cluster-id prod-cluster \
  --object-store s3 \
  --bucket S3_BUCKET \
  --aws-access-key-id AWS_ACCESS_KEY_ID \
  --aws-secret-access-key AWS_SECRET_ACCESS_KEY \
  --mode query \
  --num-io-threads 6 \
  --datafusion-num-threads 10 \
  --file-cache-size 16GB \
  --file-cache-recency 24h \
  --replica-max-buffer-size 8GB

Dedicated compactor (8 cores)

influxdb3 serve \
  --node-id compact01 \
  --cluster-id prod-cluster \
  --object-store s3 \
  --bucket S3_BUCKET \
  --aws-access-key-id AWS_ACCESS_KEY_ID \
  --aws-secret-access-key AWS_SECRET_ACCESS_KEY \
  --mode compact \
  --num-io-threads 5 \
  --datafusion-num-threads 3 \
  --compactor-input-size-budget 12GB

Downgrade options

The influxdb3 downgrade-to-parquet command reverts a cluster from the performance preview back to standard Parquet storage. For the downgrade procedure, see Downgrade to Parquet.

Migrate from pt- option names

Use the following table to update startup scripts, Helm values, or systemd environment files that use the removed --pt-* option names. There are no aliases: old --pt-* flags cause a startup error, and legacy INFLUXDB3_PT_* and INFLUXDB3_ENTERPRISE_PT_* environment variables are ignored (the server logs a warning at startup for each one that is still set).

Environment variable names follow the option names–for example, INFLUXDB3_PT_SNAPSHOT_SIZE becomes INFLUXDB3_SNAPSHOT_SIZE. Any --pt-* option not listed below drops the pt- prefix without any other change to its name.