In-place rolling upgrade (TAR/ZIP)

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

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 assume that the environment has three primaries running on three servers a, b, c. Each primary has its binaries in its default location, while the /data and /conf folders are configured using the server.directories.data configuration setting and the environment variable NEO4J_CONF. This means you can replace the DBMS binaries without affecting the configuration and state.

You must be careful to not overwrite your data or config directories when you install the new version.

Upgrade steps

On each server

  1. Download v5.y TAR or ZIP from Neo4j Download Center and unpack it in the /path/to/new directory (e.g. /path/to/new/neo4j-enterprise-5.x.y).

On server a

  1. Stop the old Neo4j:

    /neo4j-enterprise-5.x.a/bin/neo4j stop

  2. Start the new version:

    /neo4j-enterprise-5.x.y/bin/neo4j start

  3. Confirm the server is running successfully using this command to check the server has state Enabled and health Available.

    SHOW SERVERS WHERE name = [server-id]

  4. Confirm the server has started all the databases 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. Remove the old installation from /path/to/old.

On servers b and c

  1. Gradually repeat the steps you did on server a on the other servers — b and c.

  2. 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. It is advisable to monitor this log.