Upgrade InfluxDB 3 Core

Upgrade your InfluxDB 3 Core 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

• Troubleshooting a 3.12 rollback

Before you upgrade

Before upgrading InfluxDB 3 Core, 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 Core 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 <NODE_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.

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.

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

Earlier versions

Upgrade an InfluxDB 3 instance

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

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

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

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

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

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

docker stop 
CONTAINER_NAME
docker pull influxdb:core
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-core-3.12.0-windows_amd64.zip" `
  -OutFile "influxdb3-core.zip"

# Extract the binary
Expand-Archive -Path influxdb3-core.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

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.