5.3. Upgrade a Neo4j Causal Cluster

This section describes how to upgrade a Neo4j Causal Cluster.

It is recommended that your instance of Neo4j is kept up to date. Upgrading a Neo4j Causal Cluster to Neo4j 3.3.4 will ensure that you are provided with improvements in performance and security, as well as any latest bug fixes.

5.3.1. Important pre-upgrade information

All upgrades should be approached with careful planning and testing.

Pre-upgrade steps

Read Section 5.1, “Upgrade planning” thoroughly and perform all the steps listed there.


Neo4j 3.3.4 does not support rolling upgrades, so the upgrade process can involve significant downtime for the entire cluster.

If you have the infrastructure to support running the existing and the upgraded clusters at the same time, the downtime can be reduced to a small window.

Changes in a particular version

The details of a version change can be found in the Release Notes.


Neo4j does not support downgrades. However, the steps described in this section are non-destructive. If, for some reason, it is decided to not approve the upgrade and a rollback has to happen, you will put your non-upgraded database into read/write mode and start up the cluster again.

5.3.2. Upgrade process


  • You have an existing Causal Cluster in place.
  • You have a load balancer between your application and your Neo4j database.
  • You have a full backup that is stored in a safe location.


  1. Prepare the new cluster:

    1. Install Neo4j Enterprise Edition 3.3.4.
    2. Prepare the neo4j.conf files on each of the new servers. You may have to take new or changed parameters into account as per Section 5.1, “Upgrade planning”.

      Make sure that the IP addresses of the new servers are reflected in the configuration files:

      causal_clustering.initial_discovery_members=<YOUR SETUP>
  2. Set your cluster to read-only. Note: This step involves downtime.

    1. On each server in the cluster:

      1. Shut down the database.
      2. Edit neo4j.conf and set dbms.read_only to be true:

    2. Start up the servers of the old cluster, and see that the cluster forms. Now clients can access the database in read-only mode.
  3. Take a full backup of the cluster. See Section 6.2, “Perform a backup” for more information.
  4. Perform the upgrade on one of the servers in the new cluster:

    1. Save the prepared neo4j.conf into a temporary file on one of the servers in the new cluster:

      neo4j-home$ cp neo4j.conf neo4j.conf.save
    2. Edit neo4j.conf to make this a stand-alone server, and allow for upgrade:

    3. Transfer the backup onto this server.
    4. Start up Neo4j 3.3.4.

      • The database upgrade will take place during startup.
      • Information about the upgrade and a progress indicator are logged into debug.log.
    5. When the upgrade has finished, shut down the database.
    6. Perform a new backup of the upgraded database.
    7. Restore the original configuration file on this server:

      neo4j-home$ mv neo4j.conf.save neo4j.conf
  5. Prepare the cluster with the upgraded database. See Section 4.2.4, “Seed a Causal Cluster” for more information.

    1. Transfer the last backup to each of the other servers in the new cluster.
    2. Restore the backup on each machine using neo4j-admin restore:

      neo4j-home$ bin/neo4j-admin restore --from=/mnt/backup/graph.db-backup --database=graph.db --force
  6. Shut down the servers of the old cluster. Note: This step involves downtime.
  7. Re-direct the load balancers to point to the new cluster.
  8. Start up the servers of the cluster, and see that the cluster forms and is accepting transactions.
  9. For good practice purposes, make a full backup immediately after the upgrade.