Upgrade InfluxDB 3 Enterprise

Upgrade your InfluxDB 3 Enterprise version.

• Before you upgrade

• Version-specific upgrade notes

  • Back up the catalog and data before you upgrade to 3.12
  • Other changes to review before you upgrade to 3.12
  • Earlier versions

• Upgrade an InfluxDB 3 instance

• Upgrade a multi-node cluster

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

• Troubleshooting a 3.12 rollback

Before you upgrade

Before upgrading InfluxDB 3 Enterprise, verify your current version. Review the version-specific upgrade notes and release notes for compatibility requirements. Then plan your upgrade.

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

Version-specific upgrade notes

Review the notes for every release between your current version and the version you’re upgrading to.

Back up the catalog and data before you upgrade to 3.12

InfluxDB 3.12 includes a catalog record that 3.11.x can’t read. A 3.11.x node can’t load a catalog containing this record. Creating a database with --schema-mode explicit in InfluxDB 3 Enterprise writes this record.

Your catalog directory is <CLUSTER_ID>/catalog/ in your object store.

Before you start any node on 3.12:

1. Back up your data. For backup options, see Back up and restore. On the upgraded storage engine, use influxdb3 create backup.

2. Stop every node that uses the catalog. The snapshot is overwritten in place, so stopping the nodes makes the copy consistent.

3. Copy every object in your catalog/ directory to a separate location. This includes the catalog snapshot (catalog/v3/snapshot) and log files (catalog/v3/logs/). Copy the catalog directory directly, for example with cp -r or aws s3 sync. The manual backup process shows these commands. Skip its _catalog_checkpoint steps; that file doesn’t exist on current installations.

Keep the catalog and data backups until you’re sure you won’t need them for recovery.

Plan a rollback to 3.11.x

Don’t restore only a pre-upgrade catalog while retaining data written after the backup. Queries of a newly created table might then return rows written to a different table. See Queries return unexpected rows after a rollback. Contact InfluxData Support to plan a rollback for your deployment.

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.

Rolling upgrades to 3.12

During a rolling upgrade to 3.12, nodes on different versions keep working together, and you can keep changing the catalog, for example by adding tables and columns. Operations that need a 3.12 catalog record, such as creating a database with --schema-mode explicit, fail until every running node runs 3.12. These operations return an error similar to the following:

record id <N> exceeds the cluster's committed feature level (core=<N>, enterprise=<N>); the cluster must finish upgrading before this operation is available

Earlier versions

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.

For how each release affects nodes running different versions, see Version-specific upgrade notes.

Multi-node upgrade procedure

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

Before you upgrade any node, back up your data and catalog. See Back up the catalog and data before you upgrade to 3.12. For backup procedures, see Back up and restore.

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
for sts in $(kubectl get statefulset --namespace 
NAMESPACE
 --output name); do
  kubectl rollout status --namespace 
NAMESPACE
 "$sts"
done

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

# Upgrade one host at a time, ingest nodes first.
- hosts: influxdb3_ingest
  serial: 1
  vars:
    # Pin the target version so every host lands on the same build.
    influxdb3_version: "3.12.0"
  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_query, then influxdb3_compact, then influxdb3_process.

[Service]
KillSignal=SIGTERM
TimeoutStopSec=300

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

Rolling upgrade constraints

Understand the constraints that apply during rolling upgrades to avoid unexpected write failures.

Writes during catalog version transitions

When upgrading from v3.3.x (or earlier) to v3.4.x, nodes running older versions cannot modify the catalog during the rolling upgrade.

Behavior by write type:

• Writes to existing measurements, tags, and fields: Succeed on all nodes, regardless of version.
• Writes that add new measurements, tags, or fields: Fail on nodes running older versions until those nodes are upgraded.

For example, if you’re upgrading from 3.2.1 to 3.5.0:

• An ingest node running 3.2.1 can write data to existing measurements.
• An ingest node running 3.2.1 cannot write data that adds new measurements, tags, or fields.
• After upgrading the ingest node to 3.5.0, it can write data that adds new measurements, tags, or fields.

When a node running an older version receives a write that attempts to add a new measurement, the write fails with an error similar to:

Error: Catalog modification failed: node is running an older version

Troubleshooting cluster upgrades

Writes fail during upgrade

If writes fail during a rolling upgrade, verify that you’re not attempting to add new measurements, tags, or fields to nodes running older versions.

1. Check the write payload to determine if it adds new measurements, tags, or fields
2. Verify the node version that received the write
3. Route writes to upgraded nodes or wait until all nodes complete the upgrade before adding new measurements, tags, or fields

Upgrade order issues

If you upgrade nodes out of the recommended order, you may experience longer periods where catalog modifications are blocked.

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.

Catalog version constraints

Different version transitions may have different catalog version constraints. The v3.3.x → v3.4.x transition has specific constraints, but other version transitions may differ.

Before upgrading, review the release notes for your target version to understand:

• Whether the upgrade crosses a catalog version boundary
• How long catalog modifications may be blocked during the upgrade
• Any special upgrade procedures or constraints

Troubleshooting a 3.12 rollback

3.11.x fails to start after running 3.12

If a 3.11.x node can’t load the catalog after running 3.12, the catalog might contain a record that 3.11.x can’t read. Don’t restore only an older catalog to get past the error. Preserve the catalog and data files, and contact InfluxData Support to plan recovery.

Queries return unexpected rows after a rollback

If you restore a catalog backup taken before the upgrade but keep data written afterward, the catalog and data files can describe different tables. A table created after the rollback can return rows written to another table before the rollback.

If queries return unexpected rows, stop writes and preserve the current catalog and data files. Contact InfluxData Support before creating more databases or tables or attempting another restore.