In-place rolling upgrade (Docker)

This example shows how to perform an in-place rolling upgrade of a v5.x cluster running on Docker.

It is recommended to read the following pages before continuing:

For critical systems, it is recommended to:

  • Backup your server(s), including databases, configuration, and encryption keys to avoid losing data in case of failure.

  • Perform the upgrade in a test environment.

Before upgrading your cluster, ensure that it is in a healthy state. For example, this query checking for servers that are not hosting the databases they are expected to host should return no results:

SHOW SERVERS YIELD name, hosting, requestedHosting, serverId WHERE requestedHosting <> hosting

If you have composite databases, they currently do not appear in requestedHosting, and so all servers are returned by this query. You need to manually compare the hosting and requestedHosting fields, excluding any composite databases.

And this one checking for databases that are not in their expected state should also return no results:

SHOW DATABASES YIELD name, address, currentStatus, requestedStatus, statusMessage WHERE currentStatus <> requestedStatus RETURN name, address, currentStatus, requestedStatus, statusMessage

The following example steps are based on the following pre-upgrade state:

  • The environment has three cluster members located on three different servers a, b, c.

  • Neo4j DBMS v5.x is running in a Docker container on each server with /data directory in the container mapped to /path/to/data on the host machine and the container is named neo4j-dbms. You can achieve this, for instance, by running the following command on each server:

    docker run -d \
    --name=neo4j-dbms \
    --volume=/path/to/data:/data \
    neo4j:5.x-enterprise

Upgrade steps

  1. On server a, stop the container neo4j-dbms by running:

    docker stop neo4j-dbms

  2. Remove neo4j-dbms container:

    docker rm neo4j-dbms

  3. Start a v5.y container, named neo4j-dbms:

    docker run -d --name neo4j-dbms -v /path/to/data:data neo4j:5.y

    The upgrade process takes place during startup.

  4. Gradually repeat the same steps on servers b and c.

  5. If you are using version 5.8 or before, you need to manually upgrade the system database. If you are using version 5.9 or later, you can skip this step, the system database is automatically upgraded when safe to do so. Run CALL dbms.upgrade() against the cluster using Cypher Shell or another Cypher client.

Monitor the logs

The neo4j.log file contains information on how many steps the upgrade will involve and how far it has progressed.

Neo4j logging output is written to files in the /logs directory. This directory is mounted as a /logs volume.