In-place rolling upgrade of a cluster

Important

It is recommended to read the Introduction and Upgrade to 5.x or 5 LTS before continuing.

In Neo4j version 5.23, the discovery service v1 was deprecated, and the discovery service v2 was introduced. In the 2025.01 release, discovery service v1 is removed. Therefore, transitioning from v1 to v2 is strongly recommended and must be completed before upgrading to Neo4j 2025.01. For more details, please refer to the Operations Manual → Moving from discovery service v1 to v2.

This is an example of how to do a rolling upgrade, by upgrading individual servers one at a time. This approach keeps the cluster available throughout the upgrade. However, it does reduce fault tolerance while each server is offline.

Before you begin

Perform these steps in full on each server, before moving on to the next server. You must ensure that the cluster returns to a stable state before moving on to the next.

Upgrade steps (to be repeated for each server)

  1. Check the cluster is healthy.

    1. Use the following query to check servers are hosting all their assigned databases. The query should return no results:

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

      Up to version 5.9, if you have composite databases, they will not appear in requestedHosting, and so all servers are returned by this query. Thus, you must manually compare the hosting and requestedHosting fields, excluding any composite databases. From version 5.10 onwards, composite databases appear in both hosting and requestedHosting fields.

    2. Use the following query to check all databases are in their expected state. The query should return no results:

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

  2. For in-place rolling upgrades, the steps for an individual server are identical to upgrading a standalone server. The exact steps depend on how you have chosen to deploy Neo4j.

    Examples are available for common deployments:

  3. Once the server has been restarted, confirm the server is running successfully.

    Run the following command and check the server has state Enabled and health Available.

    SHOW SERVERS WHERE name = [server-id];

  4. Confirm that the server has started all the databases that it should.

    This command shows any databases that are not in their expected state:

    SHOW DATABASES YIELD name, address, currentStatus, requestedStatus, serverID WHERE currentStatus <> requestedStatus AND serverID = [server-id] RETURN name, address, currentStatus, requestedStatus

  5. Repeat these steps on the next server, until all servers are upgraded.

Manually upgrade the system database

If you are on 5.8 or an earlier version of Neo4j, you must manually upgrade the system database. Connect to the system database on any of the servers and run the following procedure:

CALL dbms.upgrade();

From version 5.9, the system database is automatically upgraded when safe.

Monitor the logs

When Neo4j restarts, it is a good idea to monitor the logs for any errors or warnings caused by the upgrade. The neo4j.log file contains information on the upgrade.