Prev |  | Next

## 24.5. Upgrading a Neo4j HA Cluster

This document describes the steps required to upgrade a Neo4j cluster without disrupting its operation. This process is referred to as a rolling upgrade.

### 24.5.1. Upgrading from 1.9.x to 2.0

It is currently not possible to do a rolling upgrade from 1.9.x to 2.0. This means that in order for you to upgrade a 1.9.x cluster to 2.0, you will incur some downtime.

#### Steps

In order to upgrade a cluster from 1.9.x to 2.0, you will need to do the following manually:

1. Backup your data!
2. Shut down every cluster member except the master.
3. Install the new version of Neo4j for each slave instance — removing the data directory, but keeping the configuration.
4. Shut down the master — this brings your cluster completely offline!
5. Follow the instructions found in Section 22.4.2, “Explicit Upgrade” for just the master instance — the data in master instance have now been converted to the new Neo4j 2.0 format.
6. Shut down the master instance again.
7. Distribute the data directory from master to each slave instance — this saves time by not having to re-build stores and indexes for each slave.
8. Bring master online.
9. Bring slaves online.

Your entire cluster has now been completely converted to Neo4j 2.0.

### 24.5.2. Upgrading from 1.8.x to 1.9

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

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.

#### 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 24.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.

#### Step 2: Upgrade the master, complete the procedure

| Warning
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.

#### 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.

### 24.5.3. Upgrading within the 1.9.x series

| Warning
Due to an bug in the HA code, it may not be possible to do a rolling (i.e. uninterrupted) upgrade to Neo4j 1.9.2 on 1.9 or 1.9.1 clusters. Attempting to do so may lead to an unstable cluster and data loss may occur. It is suggested that upgrades to 1.9.2 happen offline, where all instances are shutdown, upgraded and restarted. Upgrading from 1.9.2 to any other version works as described elsewhere in this guide.

Upgrading between 1.9.x versions follows the same general pattern as described in the first part of this guide, but is much simpler because of the compatibility of the configuration options between 1.9.x releases. We will describe a step by step procedure, aimed at reducing the master switches to a single change.

#### Step 1: On each slave perform the upgrade

Download and unpack the new version. Copy over any configuration settings, ensuring that newly introduced settings have proper values (see Section 24.2, “Setup and configuration”). 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.x the proper command would be

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

Next install the neo4j service, which also starts it

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

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

#### Step 2: Upgrade the master, complete the procedure

Go to the current master and execute step 1 The moment it will be stopped another instance will take over, transitioning the cluster to the new 1.9.x version. Finish Step 1 on this machine as well and you will have completed the process.

Copyright © 2014 Neo Technology

Prev | Up | Next
| Home |