How to upgrade InfluxDB 3 Core

Upgrading InfluxDB 3 Core replaces the running server image while keeping the same object-store prefix and node ID. A controlled Docker upgrade is useful when a Core deployment is pinned to an older image and needs a newer release without losing queryable data.

A file-backed Docker container makes the image tag, mount paths, and start command visible at the replacement point. The replacement container must use the same node-id and data mount because Core reads catalog, WAL, and Parquet data from that object-store prefix.

InfluxDB 3.10 upgrades the on-disk catalog format on first startup, and 3.9.x or older binaries cannot read that upgraded catalog. Take a rollback copy before starting the newer image, and treat restore from that backup as the rollback path if the new release cannot serve the existing data.

1. Export an admin or read token for the upgrade checks.

   $ export INFLUXDB3_AUTH_TOKEN='INFLUXDB_ADMIN_TOKEN'

   Use a real token only in the private shell that runs the upgrade. Keep raw tokens out of shared transcripts, screenshots, shell history, and committed files.

2. Check the currently running Core version.

   $ docker exec influxdb3-core env -u LOG_FILTER influxdb3 --version
   influxdb3 InfluxDB 3 Core, 3.9.3, revision e8cd4f7262c40eea9702ae97870480fdfdd76fa1

3. Query a known row before changing the container.

   $ docker exec --env INFLUXDB3_AUTH_TOKEN="$INFLUXDB3_AUTH_TOKEN" influxdb3-core env -u LOG_FILTER influxdb3 query --database sensors --format csv "SELECT room, temperature FROM weather"
   room,temperature
   lab,21.8

   Use a small query that proves an existing database and table are readable before the image changes.
   Related: How to run an SQL query in InfluxDB 3 Core

4. Create the rollback backup directory.

   $ mkdir -p /srv/influxdb3/backups/pre-3.10

5. Copy the complete node prefix before the first 3.10 startup.

   $ cp -a /srv/influxdb3/core/core01 /srv/influxdb3/backups/pre-3.10/

   Starting InfluxDB 3.10 against a 3.9 catalog upgrades that catalog in place. Restoring this backup is the rollback path if an older binary must read the data again.

6. Inspect the rollback copy.

   $ ls /srv/influxdb3/backups/pre-3.10/core01
   catalog
   table-index-conversion-completed
   wal

   Small file-backed instances may not show every possible object-store directory. Keep the whole node prefix together instead of copying only one visible subdirectory.
   Related: How to back up and restore InfluxDB 3 Core

7. Pull the target InfluxDB 3 Core image.

   $ docker pull influxdb:3.10-core
   3.10-core: Pulling from library/influxdb
   Digest: sha256:b3e577f38c19963597170d8850a3a7f77af8f0cfa866c64cd13e5de0f238e114
   Status: Image is up to date for influxdb:3.10-core
   docker.io/library/influxdb:3.10-core

   Use the exact target tag approved for the maintenance window. Avoid moving tags when the rollback decision depends on a specific release.
   Related: How to pin InfluxDB Docker image tags

8. Stop the current container.

   $ docker stop influxdb3-core
   influxdb3-core

   Writes and queries fail while the container is stopped. Run this during a maintenance window or after upstream clients are paused.

9. Remove the stopped container definition.

   $ docker rm influxdb3-core
   influxdb3-core

   Remove only the stopped container. Do not delete the mounted data path, object-store bucket prefix, Docker volume, or rollback backup.

10. Start the replacement container with the same node ID and mounts.

    $ docker run --detach \
      --name influxdb3-core \
      --publish 8181:8181 \
      --mount type=bind,src=/srv/influxdb3/core,dst=/var/lib/influxdb3/data \
      --mount type=bind,src=/srv/influxdb3/plugins,dst=/var/lib/influxdb3/plugins \
      influxdb:3.10-core influxdb3 serve \
      --node-id core01 \
      --object-store file \
      --data-dir /var/lib/influxdb3/data \
      --plugin-dir /var/lib/influxdb3/plugins
    4a5f81bd1c2e

    Keep the node-id and data mount aligned with the original container. Change only the image tag and any startup option that was already approved for the upgrade.

11. Check the upgraded Core version.

    $ docker exec influxdb3-core env -u LOG_FILTER influxdb3 --version
    influxdb3 InfluxDB 3 Core, 3.10.0, revision a1e8994464c3fe0b44ee85e95c0714ad557ed7fc

12. Confirm the recreated container uses the target image tag.

    $ docker ps --filter name=influxdb3-core
    CONTAINER ID   IMAGE                 COMMAND                  CREATED         STATUS         PORTS                                       NAMES
    4a5f81bd1c2e   influxdb:3.10-core    "influxdb3 serve --…"    8 seconds ago   Up 7 seconds   0.0.0.0:8181->8181/tcp, [::]:8181->8181/tcp   influxdb3-core

13. Query the same row after the replacement.

    $ docker exec --env INFLUXDB3_AUTH_TOKEN="$INFLUXDB3_AUTH_TOKEN" influxdb3-core env -u LOG_FILTER influxdb3 query --database sensors --format csv "SELECT room, temperature FROM weather"
    room,temperature
    lab,21.8

    If the version, image tag, and pre-upgrade query result all match expectations after the replacement, the upgraded container is serving the existing data.