Upgrade InfluxDB 3 Enterprise
Upgrade your InfluxDB 3 Enterprise version.
Before you upgrade
Before upgrading your InfluxDB 3 Enterprise cluster, review the release notes for compatibility requirements and then plan your upgrade strategy.
Upgrading to InfluxDB 3.10 is a one-way migration
The first time you start InfluxDB 3.10, it automatically upgrades the on-disk catalog format from v2 to v3. After migration, 3.9.x and older binaries are unable to read the new catalog, and fail to start on the same cluster data.
Before upgrading, back up {prefix}/catalogs/ and {prefix}/_catalog_checkpoint.
Restoring these objects is the only way to roll back to 3.9.x.
If your cluster uses the upgraded storage engine (the default for new clusters, or after running the storage engine upgrade with --upgrade-pacha-tree), data written in the new .pt file format is also unreadable by 3.9.x.
Verify your current version
Before upgrading, verify the InfluxDB 3 Enterprise version running on each node.
influxdb3 --versiondocker exec CONTAINER_NAME influxdb3 --versionReplace the following:
CONTAINER_NAME: The name of your InfluxDB 3 Enterprise container
The command returns version information similar to the following:
influxdb3 3.11.0Verify your InfluxDB version
Before and after upgrading, verify the InfluxDB 3 Enterprise version running on your instance.
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.11.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
# 4. Install the new binary
sudo cp influxdb3 /usr/local/bin/
# 5. Start the service
sudo systemctl start influxdb3docker stop CONTAINER_NAME
docker pull influxdb:enterprise
docker start CONTAINER_NAMEReplace the following:
CONTAINER_NAME: The name of your InfluxDB 3 Enterprise container
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.11.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 influxdb3Upgrade 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.
Important version transitions
- 3.4.x: Introduced a catalog version update that requires all nodes to upgrade before catalog modifications can resume.
- 3.2.x to 3.5.x: Nodes running 3.2.1 can temporarily coexist with nodes running 3.5.0, but catalog modifications are blocked until all nodes complete the upgrade.
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:
- 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.
- Query nodes: Upgrade query nodes after upgrading all ingest nodes.
- Compactor nodes: Upgrade compactor nodes last, as they have minimal impact on catalog modifications.
- 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
# 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
# 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"Replace the following:
ADMIN_TOKEN: An admin token
# 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"Replace the following:
CONTAINER_NAME: The name of your InfluxDB 3 Enterprise containerNODE_ID: The node identifier for this instanceCLUSTER_ID: The cluster identifier for your deploymentOBJECT_STORE_TYPE: The object store type (for example,file,s3,azure, orgoogle)ADMIN_TOKEN: An admin token
Use the influxdb:enterprise image tag
The influxdb:enterprise tag always points to the latest InfluxDB 3 Enterprise release.
Use docker pull influxdb:enterprise to pull the latest version, or specify a version tag directly (for example, influxdb:3.11.0-enterprise) to upgrade to a specific version.
If you use a cloud object store (S3, Azure, or Google Cloud), include the appropriate credentials and bucket configuration in the docker run command.
# 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"Replace the following:
ADMIN_TOKEN: An admin token
Use the influxdb:enterprise image tag
The influxdb:enterprise tag always points to the latest InfluxDB 3 Enterprise release.
Update the image: field in your compose.yaml to influxdb:enterprise to pull the latest version, or specify a version tag directly (for example, influxdb:3.11.0-enterprise) to upgrade to a specific version.
The InfluxDB 3 Enterprise Helm chart
runs a separate StatefulSet for each node mode, but the image tag
(image.tag) is a single chart-wide value.
A plain helm upgrade therefore rolls every node mode at once, and Kubernetes
doesn’t order rollouts across StatefulSets—so the upgrade doesn’t follow the
recommended node upgrade order on its own.
To control the order, freeze the modes you aren’t upgrading yet with the
updateStrategy.rollingUpdate.partition field, then release them one mode at a
time.
Setting partition to a value greater than or equal to a StatefulSet’s replica
count holds every pod in that StatefulSet at its current version.
A partition lower than the replica count lets the pods at or above that ordinal
update, so use a ceiling that your replica counts can’t reach.
# 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 nodesReplace the following:
RELEASE_NAME: Your Helm release nameNAMESPACE: The namespace of your releaseVERSION: The target version (for example,3.11.0)
Raise the termination grace period before upgrading
The chart doesn’t set terminationGracePeriodSeconds, so pods inherit the
Kubernetes default of 30 seconds.
If a node is still flushing its write-ahead log when Kubernetes sends
SIGKILL, it stops ungracefully and has to replay its WAL on restart.
Raise the grace period above your observed shutdown time before you roll a
cluster—see
Deploy with an orchestrator.
A rollout is a restart, not a removal
Each pod keeps its StatefulSet-ordinal name, so every node re-registers under
its existing node ID.
Don’t run
influxdb3 remove node
as part of an upgrade—removal permanently deletes the node’s catalog entry and
object-store files.
See Restart compared to removal.
helm rollback doesn’t undo a catalog migration
helm rollback reverts the image tag, but it can’t revert changes the newer
version already made to your cluster data.
After a node starts InfluxDB 3 Enterprise 3.10 or later, the on-disk catalog is
migrated to v3 and older binaries fail to start against it—so rolling the
release back leaves pods crash-looping on a catalog they can’t read.
Restoring the catalog objects you backed up is the only way back.
See Upgrading to InfluxDB 3.10 is a one-way migration.
Drive the upgrade one node at a time with serial: 1, and order your plays by
node mode to match the
recommended node upgrade order.
# 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.11.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.Because systemd escalates to SIGKILL after TimeoutStopSec, confirm your
unit file allows enough time for the final WAL flush before you roll a cluster:
[Service]
KillSignal=SIGTERM
TimeoutStopSec=300Restart in place—don’t remove nodes
Each host restarts with the same
--node-id, so it
re-registers as the same node.
Never add
influxdb3 remove node
to an upgrade playbook—see
Restart compared to removal.
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 versionTroubleshooting 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.
- Check the write payload to determine if it adds new measurements, tags, or fields
- Verify the node version that received the write
- 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.
- Connect to each node and verify the version
- 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
Was this page helpful?
Thank you for your feedback!
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB 3 Enterprise and this documentation. To find support, use the following resources:
Customers with an annual or support contract can contact InfluxData Support. Customers using a trial license can email trial@influxdata.com for assistance.