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
  • 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.
• Processing Engine in a cluster: A WAL trigger now runs on a process node for writes sent to any ingest node, and the default --node-spec all makes every node that runs the Processing Engine own the trigger. When you upgrade a cluster, move your plugins to a standalone process node, remove --plugin-dir from the other nodes, and pin each trigger to the process node with --node-spec. See Configure a standalone Processing Engine.
• 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.2

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.2_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.2-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 how nodes on different versions interoperate and the recommended upgrade order for different node modes.

• Mixed-version clusters
• Multi-node upgrade procedure
• Troubleshooting cluster upgrades

Mixed-version clusters

During a rolling upgrade, nodes on the old and new versions share the catalog and the files in object storage. How the cluster behaves depends on the versions you upgrade from and to:

• From 3.10 or later: Nodes on the old version keep reading and writing the catalog until the last of them is upgraded. Features added by the new version stay unavailable until every running node is on it. The cluster then commits the new feature level, and binaries on the old version can no longer start against the catalog.
• To 3.9 or earlier: Upgrades that cross the catalog format change in 3.1 or 3.4 block writes that add tables, tags, or fields on nodes on the old version until they’re upgraded. Other upgrades to 3.9 or earlier don’t affect the catalog.
• From 3.9 or earlier to 3.10 or later: Not a rolling upgrade. The first node on the new version migrates the catalog, and nodes on 3.9 or earlier can’t read the migrated catalog. Stop every node, upgrade them all, and then start the cluster. See Upgrading to InfluxDB 3.10 is a one-way migration.

Multi-node upgrade procedure

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

Recommended node upgrade order

The order depends on the versions you upgrade from and to.

Upgrading from 3.10 or later:

Upgrade the nodes that read other nodes’ output before the nodes that write it. Within a mode, upgrade one node at a time so the others keep serving.

1. Query nodes
2. Process nodes
3. Compactor nodes
4. Ingest nodes

A node that runs ingest mode together with query or process mode (a plugin directory adds process mode) both reads and writes files. Upgrade such nodes back to back, or stop them together when the release notes announce a file format change.

Upgrading to 3.9 or earlier across the catalog format change in 3.1 or 3.4:

Upgrade ingest nodes first to restore writes that add tables, tags, or fields, then query, compactor, and process nodes. For other upgrades to 3.9 or earlier, the order doesn’t matter.

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 queriers roll.
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 \
  --reuse-values \
  --set image.tag=
VERSION
-enterprise \
  --set processingEngine.updateStrategy.rollingUpdate.partition=10000 \
  --set compactor.updateStrategy.rollingUpdate.partition=10000 \
  --set ingester.updateStrategy.rollingUpdate.partition=10000

# 2. Wait for the querier pods to roll and become ready
kubectl rollout status statefulset --namespace 
NAMESPACE
 \
  --selector app.kubernetes.io/component=querier

# 3. Release the processing engine and wait for it to roll
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 --reuse-values \
  --set processingEngine.updateStrategy.rollingUpdate.partition=0
kubectl rollout status statefulset --namespace 
NAMESPACE
 \
  --selector app.kubernetes.io/component=processor

# 4. Release the compactor and wait for it to roll
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 --reuse-values \
  --set compactor.updateStrategy.rollingUpdate.partition=0
kubectl rollout status statefulset --namespace 
NAMESPACE
 \
  --selector app.kubernetes.io/component=compactor

# 5. Release the ingesters and wait for them to roll
helm upgrade 
RELEASE_NAME
 influxdata/influxdb3-enterprise \
  --namespace 
NAMESPACE
 --reuse-values \
  --set ingester.updateStrategy.rollingUpdate.partition=0
kubectl rollout status statefulset --namespace 
NAMESPACE
 \
  --selector app.kubernetes.io/component=ingester

# 6. Verify every node re-registered and reports running
influxdb3 show nodes

# Upgrade one host at a time, query nodes first.
- hosts: influxdb3_query
  serial: 1
  vars:
    # Pin the target version so every host lands on the same build.
    influxdb3_version: "3.12.2"
  tasks:
    - name: Stop influxdb3 gracefully
      ansible.builtin.systemd_service:
        name: influxdb3
        state: stopped

    # Replace this task with the install method you use--for example, a
    # package from your own repository or the downloaded release archive.
    # See https://docs.influxdata.com/influxdb3/enterprise/install/
    - name: Install influxdb3 {{ influxdb3_version }}
      ansible.builtin.include_role:
        name: influxdb3_install

    - name: Start influxdb3
      ansible.builtin.systemd_service:
        name: influxdb3
        state: started

    - name: Wait for the node to report healthy
      ansible.builtin.uri:
        url: "http://{{ inventory_hostname }}:8181/health"
        status_code: 200
      register: health
      until: health.status == 200
      retries: 30
      delay: 10

# Repeat for influxdb3_process, then influxdb3_compact, then influxdb3_ingest.

[Service]
KillSignal=SIGTERM
TimeoutStopSec=300

Repeat these steps for each remaining node in the recommended order.

Troubleshooting cluster upgrades

Upgrade order issues

If you upgrade nodes out of the recommended order, a query or process node on the old version may encounter files in a format it can’t read. It logs errors and keeps serving the data it already loaded; if it restarts, it fails to start. Upgrade the node to recover.

New features stay unavailable after the upgrade

The cluster commits a new feature level only when every running node is on the new version. Run influxdb3 show nodes; a node that stopped without a clean shutdown can still show as running and holds the feature level back. Restart that node on the new version.

Nodes upgrade out of order in Helm deployments

The InfluxDB 3 Enterprise Helm chart uses a single chart-wide image.tag, so a plain helm upgrade rolls every node mode at once instead of following the recommended node upgrade order. Use updateStrategy.rollingUpdate.partition to release one mode at a time, as shown in the Helm tab of Perform a rolling upgrade.

Nodes don’t return to running after a rollout

A node that was killed before it finished flushing its write-ahead log stops ungracefully and replays its WAL on restart, which can extend startup. In Kubernetes, this usually means terminationGracePeriodSeconds (default 30) is shorter than the node’s shutdown time; with systemd, it usually means TimeoutStopSec is too low. See Deploy with an orchestrator.

Extra nodes appear in the catalog after an upgrade

Each restart registered a new node ID instead of reclaiming the existing one. Verify that your deployment assigns a stable --node-id—a Kubernetes Deployment generates a new pod name on every rollout, so use a StatefulSet instead. See Kubernetes and Helm.

Version compatibility problems

If nodes fail to communicate after an upgrade, verify that all nodes are running compatible versions.

1. Connect to each node and verify the version
2. Review the release notes for your target version to identify any breaking changes or compatibility requirements.