E.5. Upgrade

This section describes how to upgrade a Neo4j HA cluster.

Upgrading a Neo4j HA cluster requires following a specific process in order to ensure that the cluster remains consistent, and that all cluster instances are able to join and participate in the cluster following their upgrade.

Pre-upgrade steps
Downtime
Neo4j 3.5.8 does not support rolling upgrades for HA clusters, so the upgrade process can involve significant downtime for the entire cluster. A test upgrade on a production-like equipment provides information on the duration of the downtime.
Rollback
Neo4j does not support downgrades. If the upgrade is not successful, you have to do a full rollback, including restoring a pre-upgrade backup.
Upgrade steps

  1. Shut down the cluster

    1. Shut down the slave instances, one by one.
    2. Shut down the master last.

  2. Upgrade the master

    1. Install Neo4j 3.5.8 on the master, keeping the database directory (in a default configuration: data/databases/graph.db) untouched.
    2. Set dbms.mode=SINGLE in neo4j.conf to disable HA in the configuration.
    3. Follow the single instance upgrade instructions to upgrade Neo4j.
    4. When upgrade has completed, shut down Neo4j again.
    5. Set dbms.mode=HA in neo4j.conf to re-enable HA in the configuration.

    6. Make a full backup of the Neo4j database.

      Please note that backups taken before the upgrade are no longer valid for update via the incremental online backup. Therefore, it is important to perform a full backup, using an empty target directory, at this point.

  3. Upgrade the slaves

    On each slave:

    1. Remove the database directory (in a default configuration: data/databases/graph.db).
    2. Install Neo4j 3.5.8.
    3. Review the settings in the configuration files in the previous installation, and transfer any custom settings to the 3.5.8 installation.

    4. If applicable, copy the security configuration from the master, since this is not propagated automatically.

      Alternatively, at this point you can manually copy the database directory from the master to the slaves. Doing so will avoid the need to sync from the master when starting. This can save considerable time when upgrading large databases.

  4. Restart the cluster

    1. Start the master instance.

    2. Start the slaves, one by one.

      Once a slave has joined the cluster, it will sync the database from the master instance.