23.5. Upgrade of a Neo4j HA Cluster

[Caution]Caution

Before attempting any of the upgrades described here, please backup your database store!

To upgrade a Neo4j HA cluster to Neo4j 2.1.4 requires following a specific process that ensures the cluster remains consistent and all cluster instances are able to join and participate following their upgrade.

Neo4j supports two approaches to HA cluster upgrades, the standard upgrade process and the rolling upgrade process for zero downtime.

[Note]Note

It is strongly recommended to follow the standard upgrade process over the rolling upgrade process, as it is much simpler and less likely to encounter issues.

[Important]Important

After upgrade is complete, existing backups will not be suitable for updating via the incremental online backup. Please ensure that the first backup after upgrading uses an empty target directory, and thus performs a full backup.

Standard upgrade

In order to perform a cluster upgrade to Neo4j 2.1.4, you need to first upgrade the database store on a single instance, and then allow that store to propagate out to slaves.

Steps

The following process is recommended:

Backup

Shut down the cluster

  • Shut down all instances. This is usually best done one instance after the other, rather than all at once. It is also strongly recommended to shutdown the master of the cluster last.

Upgrade the database store on the previous master

  1. Install Neo4j 2.1.4 on the previous master, keeping the database store (typically data/graph.db) from the previous version.
  2. Disable HA in the configuration, by setting org.neo4j.server.database.mode=SINGLE.
  3. Upgrade as described for a single instance of Neo4j (this may involve configuring with allow_store_upgrade=true, as described in "Explicit Upgrades").
  4. Once upgraded, shut down Neo4j again.
  5. Re-enable HA in the configuration, by setting org.neo4j.server.database.mode=HA again.

Upgrade the slaves

  • Install Neo4j 2.1.4 on all previous slaves and remove their database store (typically data/graph.db). Slave should not be started with a previous store present.

Restart the cluster

  1. Start the previous master instance.
  2. Start each slave, one after the other. Once joined, they will sync the store from the master instance.
[Note]Note

For larger databases, it is possible to manually copy the database store from the previous master after it has completed the upgrade to the slaves before starting them. This will avoid the need for them to sync from the master at startup time.

Rolling upgrade

Upgrading a Neo4j cluster without disrupting its operation is referred to as a rolling upgrade.

[Important]Important

Neo4j 2.1.4 only supports rolling upgrades from Neo4j 2.0.x and previous Neo4j 2.1.x patch releases.

[Caution]Caution

It is not possible to downgrade a Neo4j cluster without downtime.

In order to perform a rolling upgrade to Neo4j 2.1.4, you need to first upgrade the database store and then replace the database store of each cluster instance with the upgraded version, one at a time, with the cluster master done last.

Steps

The following process is recommended:

Backup

Upgrade a single database store

  • Perform upgrade, using one slave instance to do so:

    1. Shut down a single slave instance.
    2. Install Neo4j 2.1.4 on that instance, keeping the database store (typically data/graph.db) from the previous version.
    3. Disable HA in the configuration, by setting org.neo4j.server.database.mode=SINGLE.
    4. Upgrade as described for a single instance of Neo4j. This may involve configuring with allow_store_upgrade=true, as described in "Explicit Upgrades").
    5. Once upgraded, shut down Neo4j again.
    6. Copy the upgraded database store (typically data/graph.db) to a separate location.
[Warning]Warning

You must also ensure any external application will not attempt to access this instance whilst it performs the upgrade in SINGLE mode. You should either disable access externally (e.g. in the load balancer), or by reconfiguring the port Neo4j will listen on, such that it cannot be found (e.g. temporarily set org.neo4j.server.webserver.port=7470).

Rejoin the slave to the cluster:

  1. Re-enable HA in the configuration (setting org.neo4j.server.database.mode=HA). Also restore any webserver port changes.
  2. Start up, and allow to join the cluster.

Upgrade remaining slaves

  • Repeat for each remaining slave:

    1. Shut down the slave.
    2. Replace the entire database store directory (typically data/graph.db) with the upgraded copy.
    3. Start up slave, allow to join the cluster and sync any new transactions.

Upgrade the master

  1. Shut down the master
  2. Wait for failover to occur to one of the slaves.
  3. Replace the entire database store directory (typically data/graph.db) with the upgraded copy.
  4. Start up the old master, and allow to join the cluster. It will now be a slave.

Your entire cluster has now been completely upgraded to Neo4j 2.1.4.

Downgrading

Downgrade is only supported between Neo4j versions that for automatic upgrades. This typically means only within patch releases of the same Neo4j version.

Downgrade follows the same process as for standard upgrade.