In-place rolling upgrade of a cluster

Important

It is recommended to read the Introduction and Changes from Neo4j 5 to 2025.x before continuing.

In the 2025.01 release, discovery service v1 is removed. Therefore, you must transition to v2 before upgrading to Neo4j 2025.01. For more details, please refer to the Operations Manual → Moving from discovery service v1 to v2. Additionally, the dbms.cluster.discovery.version setting is ignored in Neo4j 2025.01 and later, and dbms.cluster.discovery.v2.endpoints is deprecated in favor of dbms.cluster.endpoints. Therefore, it is recommended to remove dbms.cluster.discovery.version and replace dbms.cluster.discovery.v2.endpoints with dbms.cluster.endpoints in the neo4j.conf file of each server when replacing the binaries. Otherwise, you can do this at a later time.

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)

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
  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
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:
(Recommended when moving from Neo4j 5.26) Before you restart the server, remove dbms.cluster.discovery.version and replace dbms.cluster.discovery.v2.endpoints with dbms.cluster.endpoints in the neo4j.conf file.
Restart the server and confirm that it is running successfully.

Run the following command and check the server has state Enabled and health Available.
```
SHOW SERVERS WHERE name = [server-id];
```

Confirm that all the databases are in their expected state by running the following command:

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

Repeat these steps on the next server, until you upgrade all servers.

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.