26.5. Upgrading a Neo4j HA Cluster

26.5.1. Overview
26.5.2. Step 1: On each slave perform the upgrade
26.5.3. Step 2: Upgrade the master, complete the procedure
26.5.4. Step 3: Cleanup, removing the coordinator services

This document describes the steps required to upgrade a Neo4j cluster from a previous version to 1.9 without disrupting its operation, a process referred to as a rolling upgrade. The starting assumptions are that there exists a cluster running Neo4j version 1.8 or newer with the corresponding ZooKeeper instances and that the machine which is currently the master is known. It is also assumed that on each machine the Neo4j service and the neo4j coordinator service is installed under a directory which from here on is assumed to be /opt/old-neo4j

26.5.1. Overview

The process consists of upgrading each machine in turn by removing it from the cluster, moving over the database and starting it back up again. Configuration settings also have to be transferred. It is important to note that the last machine to be upgraded must be the master. In general, the "cluster version" is defined by the version of the master, providing the master is of the older version the cluster as a whole can operate (the 1.9 instances running in compatibility mode). When a 1.9 instance is elected master however, the older instances are not capable of communicating with it, so we have to make sure that the last machine upgraded is the old master. The upgrade process is detected automatically from the joining 1.9 instances and they will not participate in a master election while even a single old instance is part of the cluster.

26.5.2. Step 1: On each slave perform the upgrade

Download and unpack the new version. Copy over any configuration settings you run your instances with, taking care for deprecated settings and API changes that can occur between versions. Also, ensure that newly introduced settings have proper values (see Section 26.2, “Setup and configuration”). The most important thing about the settings setup is the ha.coordinators setting in neo4j.properties which must be set to the value the existing 1.8 instances are using. You also have to make sure that all but one instance have the ha.allow_init_cluster setting to false - the machine that has it set to true should be the one that is to become the new master. In addition, it is necessary that the last machine to be upgraded (the 1.8 master) does not have the ha.coordinators setting present in its configuration file. Finally, don’t forget to copy over any server plugins you may have. First, shutdown the neo4j instance with

service neo4j-service stop

Next, uninstall it

service neo4j-service remove

Now you can copy over the database. Assuming the old instance is at /opt/old-neo4j and the newly unpacked under /opt/neo4j-enterprise-1.9 the proper command would be

cp -R /opt/old-neo4j/data/graph.db /opt/neo4j-enterprise-1.9/data/

Next install the neo4j service, which also starts it

/opt/neo4j-enterprise-1.9/bin/neo4j install

Done. Now check that the services are running and that webadmin reports the version 1.9. Transactions should also be applied from the master as usual.

26.5.3. Step 2: Upgrade the master, complete the procedure


Make sure that the installation that will replace the current master instance does not have ha.coordinators setting present in the neo4j.properties file.

Go to the current master and execute step 1 The moment it will be stopped another instance will take over (the one with the allow_init_cluster setting set to true), transitioning the cluster to 1.9. Finish Step 1 on this machine as well and you will have completed the process.

26.5.4. Step 3: Cleanup, removing the coordinator services

Each 1.8 installation still has a coordinator service installed and running. To have those removed you need to execute at every upgraded instance

service neo4j-coordinator stop
service neo4j-coordinator remove

After that, the 1.8 instances are no longer active or needed and can be removed or archived.