23.5. Upgrade of a Neo4j HA Cluster
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 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 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
- Before anything else, backup your database store!
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
-
Install Neo4j 2.1.4 on the previous master, keeping the database
store (typically
data/graph.db
) from the previous version. -
Disable HA in the configuration, by setting
org.neo4j.server.database.mode=SINGLE
. -
Upgrade as described for a single instance of Neo4j (this may involve configuring with
allow_store_upgrade=true
, as described in "Explicit Upgrades"). - Once upgraded, shut down Neo4j again.
-
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
- Start the previous master instance.
- Start each slave, one after the other. Once joined, they will sync the store from the master instance.
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 Neo4j 2.1.4 only supports rolling upgrades from Neo4j 2.0.x and previous Neo4j 2.1.x patch releases. |
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
- Before anything else, backup your database store!
Upgrade a single database store
-
Perform upgrade, using one slave instance to do so:
- Shut down a single slave instance.
-
Install Neo4j 2.1.4 on that instance, keeping the database store (typically
data/graph.db
) from the previous version. -
Disable HA in the configuration, by setting
org.neo4j.server.database.mode=SINGLE
. -
Upgrade as described for a single instance of Neo4j. This may involve configuring with
allow_store_upgrade=true
, as described in "Explicit Upgrades"). - Once upgraded, shut down Neo4j again.
-
Copy the upgraded database store (typically
data/graph.db
) to a separate location.
Warning You must also ensure any external application will not attempt to access this
instance whilst it performs the upgrade in |
Rejoin the slave to the cluster:
-
Re-enable HA in the configuration (setting
org.neo4j.server.database.mode=HA
). Also restore any webserver port changes. - Start up, and allow to join the cluster.
Upgrade remaining slaves
-
Repeat for each remaining slave:
- Shut down the slave.
-
Replace the entire database store directory (typically
data/graph.db
) with the upgraded copy. - Start up slave, allow to join the cluster and sync any new transactions.
Upgrade the master
- Shut down the master
- Wait for failover to occur to one of the slaves.
-
Replace the entire database store directory (typically
data/graph.db
) with the upgraded copy. - 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.