Upgrade InfluxDB 3 Enterprise

Upgrade your InfluxDB 3 Enterprise version.

• Before you upgrade

  • Other changes to review before you upgrade to 3.12

• Upgrade an InfluxDB 3 instance

• Upgrade a multi-node cluster

  • Multi-node upgrade procedure
  • Rolling upgrade constraints
  • Troubleshooting cluster upgrades

Before you upgrade

Before upgrading your InfluxDB 3 Enterprise cluster, review the release notes for compatibility requirements and then plan your upgrade strategy.

Other changes to review before you upgrade to 3.12

• Query concurrency now has a finite default: --max-concurrent-queries defaults to the larger of 50 and 4 times the node’s query parallelism, instead of being effectively unlimited. Queries submitted over the limit wait for a slot instead of running immediately.
• The WAL buffer limit is now enforced: --wal-max-buffered-writes (default 100000) previously had no effect. Once the WAL buffer fills, writes now return 429 Too Many Requests until it drains.
• HTTP and gRPC request metrics are split by protocol: http_requests* metrics now count only HTTP requests, and grpc_requests* metrics count only gRPC requests. Dashboards that summed the two families report lower values after you upgrade. The path and method_path labels are now route templates, such as /api/v3/engine/:path, instead of literal paths; update panels that filter on a specific path.

Also review these InfluxDB 3 Enterprise changes:

• Data file cache is now a hard limit (upgraded storage engine): --file-cache-size now also counts bytes held by running queries. A query that needs more than the remaining budget fails instead of the node using memory beyond the configured limit.
• Nodes without query mode refuse data queries (Parquet engine): A node that doesn’t run query mode now returns 405 Method Not Allowed for data queries instead of serving them. System table queries still work.
• --node-spec no longer pins a trigger to one node: It now selects which process nodes’ schedulers own the trigger. With the default, all, every process node owns the trigger and follows every ingest node’s write-ahead log, so a WAL trigger runs once per process node for each WAL flush. To keep a WAL trigger running once per flush in a cluster with more than one process node, set --node-spec to a single node. See Run the Processing Engine in a cluster.
• Username and password sessions must be renewed: Access tokens issued to users who sign in with a username and password must now carry the cluster’s catalog UUID. Tokens issued before 3.12 are rejected: refresh the token or sign in again. API tokens aren’t affected.
• Orphaned file cleanup starts automatically (upgraded storage engine): The primary compactor begins finding and deleting unreferenced compacted files a few minutes after it first starts on 3.12, then repeats every 7 days. To only report candidates without deleting them, set --compactor-sweep-mode dry-run. To turn cleanup off, set --compactor-sweep-interval off. See Orphaned file cleanup.
• Distributed compaction is available (beta, upgraded storage engine): Compaction jobs can now run on every compact node instead of only the node that holds the compactor lease. It’s off by default (--compactor-dispatch-target local), so upgrading alone doesn’t change where compaction runs. See Distributed compaction.

For the complete list of changes, see the release notes.

Verify your current version

Before upgrading, verify the InfluxDB 3 Enterprise version running on each node.

influxdb3 --version

docker exec 
CONTAINER_NAME
 influxdb3 --version

The command returns version information similar to the following:

influxdb3 3.12.0

Upgrade an InfluxDB 3 instance

curl -O https://www.influxdata.com/d/install_influxdb3.sh \
&& sh install_influxdb3.sh enterprise

# 1. Download the new version
curl -L https://dl.influxdata.com/influxdb/releases/influxdb3-enterprise-3.12.0_linux_amd64.tar.gz \
  -o influxdb3-enterprise.tar.gz

# 2. Extract the archive
tar xvzf influxdb3-enterprise.tar.gz

# 3. Stop the service
sudo systemctl stop influxdb3-enterprise

# 4. Install the new binary
sudo cp influxdb3 /usr/local/bin/

# 5. Start the service
sudo systemctl start influxdb3-enterprise

docker stop 
CONTAINER_NAME
docker pull influxdb:enterprise
docker start 
CONTAINER_NAME

docker compose down
docker compose pull
docker compose up -d

# Download the latest Windows binary
Invoke-WebRequest `
  -Uri "https://dl.influxdata.com/influxdb/releases/influxdb3-enterprise-3.12.0-windows_amd64.zip" `
  -OutFile "influxdb3-enterprise.zip"

# Extract the binary
Expand-Archive -Path influxdb3-enterprise.zip -DestinationPath . -Force

# Stop the service, replace the binary, and start the service
Stop-Service influxdb3
Copy-Item -Path "influxdb3.exe" -Destination "C:\Program Files\InfluxData\influxdb3\" -Force
Start-Service influxdb3

Upgrade a multi-node cluster

Upgrade InfluxDB 3 Enterprise instances to newer versions using rolling upgrades to minimize downtime. When upgrading multi-node clusters, you need to understand catalog version constraints and the recommended upgrade order for different node modes.

• Catalog version compatibility
• Multi-node upgrade procedure
• Rolling upgrade constraints
• Troubleshooting cluster upgrades

Catalog version compatibility

InfluxDB 3 Enterprise uses a catalog to track metadata about tables, tags, and fields. Some versions introduce catalog version updates that affect how nodes can interoperate during rolling upgrades.

During a rolling upgrade across a catalog version boundary, nodes running older versions cannot modify the catalog. This affects writes that add new tables, tags, or fields, but allows writes to existing tables, tags, and fields.

Multi-node upgrade procedure

Follow these steps to upgrade your InfluxDB 3 Enterprise deployment with minimal downtime.

Recommended node upgrade order

The order in which you upgrade nodes affects the availability of catalog modifications during the upgrade. Different node modes have different impacts on catalog updates:

• Ingest nodes: Primarily update the catalog when accepting writes that add new tables, tags, or fields via line protocol.
• Query nodes: Can accept API requests that update the catalog (for example, influxdb3 create table), but less frequently than ingest nodes.
• Compactor nodes: Rarely modify the catalog during normal operation.
• Process nodes: Process data without modifying the catalog structure.

Recommended upgrade order:

1. Ingest nodes: Upgrade ingest nodes first to restore catalog modification capability as quickly as possible. If you have multiple ingest nodes and can route traffic while one is down, upgrade them sequentially.
2. Query nodes: Upgrade query nodes after upgrading all ingest nodes.
3. Compactor nodes: Upgrade compactor nodes last, as they have minimal impact on catalog modifications.
4. Process nodes: Can be upgraded at any time, as they don’t modify the catalog.

Perform a rolling upgrade

Follow these steps to upgrade each node in your deployment:

# 1. Stop the service
sudo systemctl stop influxdb3-enterprise

# 2. Install the new version
# Follow the installation instructions for your platform:
# https://docs.influxdata.com/influxdb3/enterprise/install/

# 3. Start the service
sudo systemctl start influxdb3-enterprise

# 4. Verify the version
influxdb3 --version

# 5. Check the node's health
influxdb3 query \
  --database _internal \
  --token ADMIN_TOKEN \
  "SELECT * FROM system.queries LIMIT 5"

# 1. Stop the container
docker stop 
CONTAINER_NAME

# 2. Pull the latest image
docker pull influxdb:enterprise

# 3. Start the container with the new image
# IMPORTANT: Adjust the docker run command to match your existing
# container configuration, including environment variables, volume mounts,
# object store settings, and network settings.
docker run -d \
  --name 
CONTAINER_NAME
 \
  -p 8181:8181 \
  -e INFLUXDB3_LICENSE_EMAIL=your-email@example.com \
  -v ~/.influxdb3/data:/var/lib/influxdb3/data \
  influxdb:enterprise \
  influxdb3 serve \
  --node-id 
NODE_ID
 \
  --cluster-id 
CLUSTER_ID
 \
  --object-store 
OBJECT_STORE_TYPE
 \
  --data-dir /var/lib/influxdb3/data

# 4. Verify the version
docker exec 
CONTAINER_NAME
 influxdb3 --version

# 5. Check the node's health
docker exec 
CONTAINER_NAME
 influxdb3 query \
  --database _internal \
  --token 
ADMIN_TOKEN
 \
  "SELECT * FROM system.queries LIMIT 5"

# 1. Stop the services
docker compose down

# 2. Update the image in your compose.yaml file
# Change the image version to: influxdb:enterprise

# 3. Start the services with the new image
docker compose up -d

# 4. Verify the version
docker compose exec influxdb3 influxdb3 --version

# 5. Check the node's health
docker compose exec influxdb3 influxdb3 query \
  --database _internal \
  --token 
ADMIN_TOKEN
 \
  "SELECT * FROM system.queries LIMIT 5"

# 1. Freeze the modes you upgrade later, then apply the new image tag.
#    Any partition >= a StatefulSet's replica count holds all of its pods, so
#    10000 is a ceiling no deployment reaches. Only ingesters roll.
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 \
  --reuse-values \
  --set image.tag=
VERSION
-enterprise \
  --set querier.updateStrategy.rollingUpdate.partition=10000 \
  --set compactor.updateStrategy.rollingUpdate.partition=10000 \
  --set processingEngine.updateStrategy.rollingUpdate.partition=10000

# 2. Wait for the ingester pods to roll and become ready
kubectl rollout status --namespace 
NAMESPACE
 \
  "$(kubectl get statefulset --namespace 
NAMESPACE
 \
    --selector app.kubernetes.io/component=ingester --output name)"

# 3. Release queriers and wait for them to roll
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 --reuse-values \
  --set querier.updateStrategy.rollingUpdate.partition=0
kubectl rollout status --namespace 
NAMESPACE
 \
  "$(kubectl get statefulset --namespace 
NAMESPACE
 \
    --selector app.kubernetes.io/component=querier --output name)"

# 4. Release the compactor and the processing engine. Process nodes have no
#    ordering requirement, so they can roll alongside the compactor.
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 --reuse-values \
  --set compactor.updateStrategy.rollingUpdate.partition=0 \
  --set processingEngine.updateStrategy.rollingUpdate.partition=0

# 5. Wait for the remaining StatefulSets to finish rolling before verifying