5.3. Upgrade a Neo4j Causal Cluster

This section describes how to upgrade a Neo4j Causal Cluster.

5.3.1. Important pre-upgrade information

All upgrades should be approached with careful planning and testing.

Pre-upgrade steps
  1. Read Section 5.1, “Upgrade planning” thoroughly and perform all the steps listed there.
  2. Perform and verify backups:

  3. Prepare a new neo4j.conf file for each of the servers in the cluster, following the instructions under the Apply configuration changes step in Section 5.1, “Upgrade planning”.

    If following instructions for Rolling upgrade for replaceable resources, all the servers that form the cluster will be replaced. Therefore, make sure that the parameter causal_clustering.initial_discovery_members is updated to reflect the new Core members.

Limitations
  • Neo4j does not support downgrades. If the upgrade is not successful, you have to do a full rollback, including restoring a pre-upgrade backup.
  • In order to minimize risk, it is recommended that while upgrading, you do not change configuration, perform architectural restructuring, or similar tasks.
Monitoring the status of cluster members
Use the procedure dbms.cluster.overview() to monitor the status of the cluster members during the upgrade.
Upgrade methods

The following are methods of upgrading a Neo4j Causal Cluster:

Installing the new Neo4j version
For instructions on how to install the software package itself, refer to Chapter 2, Installation.
Post-upgrade
Note that backups taken before the upgrade are no longer valid for update via the incremental online backup. Therefore, it is important to perform a full backup, using an empty target directory, immediately after the upgrade.

5.3.2. Rolling upgrade

Limitations
Rolling upgrades are only supported between patch releases, and only when a store format upgrade is not needed. Read the Release Notes to find out whether a certain upgrade path involves a store format change. You can also contact Customer Support to obtain this information. If you cannot use rolling upgrades, then follow the instructions for offline upgrades instead.
Downtime
Since downgrades are not supported, a failed upgrade will require recovery from a pre-upgrade backup. Therefore, the safest path is to disable write loads during the upgrade process.

5.3.2.1. Rolling upgrade for fixed servers

This variant is suitable for deployments where the servers are fixed and have to be updated in-place.

Upgrade steps
  1. On one of the Core servers:

    1. Shutdown the instance.
    2. Install Neo4j using one of the following methods, specific to your technology:

      • If using a tarball or zipfile for installation:

        1. Untar or unzip Neo4j 3.4.7.
        2. Place the neo4j.conf file, that you have prepared for this server, into the Configuration directory.
        3. Copy the data directory from the old installation to the new one. This step is not applicable if you have dbms.directories.data pointing to a directory outside of NEO4J_HOME.
      • If using a Debian or RPM distribution:

        1. Install Neo4j 3.4.7.
        2. When prompted, review the differences between the neo4j.conf files of the previous version and Neo4j 3.4.7. Transfer any custom settings to the 3.4.7 installation, as prepared in the pre-upgrade step.
    3. Start up Neo4j 3.4.7 and see it join the cluster.
  2. Repeat the previous steps for every server instance.

5.3.2.2. Rolling upgrade for replaceable resources

This variant is suitable for deployments utilizing replaceable cloud or container resources. With this method, it is possible to avoid a reduction in availability, since you are adding a new instance before removing an old instance.

Upgrade steps
  1. Configure a new instance with Neo4j 3.4.7, to replace an existing instance.
  2. Use the new neo4j.conf that you have prepared in the pre-upgrade step.
  3. If applicable, place the backed-up data/dbms directory into the data directory of the new instance.
  4. Start up the new instance, and let it complete a store copy.
  5. See the new instance join the cluster.
  6. Shutdown the old instance.
  7. Repeat the previous steps for every server instance.

5.3.3. Offline upgrade

This variant is suitable for cases where a rolling upgrade is not possible due to breaking changes, or could be undesirable for other reasons.

Downtime
If the offline upgrade method is selected, this will involve downtime. A test upgrade on a production-like equipment provides information on the duration of the downtime.
Upgrade steps
  1. Shut down all the servers in the cluster
  2. On one of the Core servers:

    1. Set dbms.mode=SINGLE in neo4j.conf.
    2. Install Neo4j using one of the following methods, specific to your technology:

      • If using a tarball or zipfile for installation:

        1. Untar or unzip Neo4j 3.4.7.
        2. Place the neo4j.conf file, that you have prepared for this server, into the Configuration directory.
        3. Set dbms.allow_upgrade=true in neo4j.conf. Neo4j will fail to start without this configuration.
        4. Copy the data directory from the old installation to the new one. This step is not applicable if you have dbms.directories.data pointing to a directory outside of NEO4J_HOME.
      • If using a Debian or RPM distribution:

        1. Set dbms.allow_upgrade=true in neo4j.conf.
        2. Install Neo4j 3.4.7.
        3. When prompted, review the differences between the neo4j.conf files of the previous version and Neo4j 3.4.7. Transfer any custom settings to the 3.4.7 installation, as prepared in the pre-upgrade step. Make sure to preserve dbms.allow_upgrade=true as set in the instruction above. Neo4j will fail to start without this configuration.
    3. Start up Neo4j 3.4.7. The database upgrade will take place during startup.
    4. For information about the upgrade and a progress indicator, these are logged into debug.log.
    5. Set dbms.allow_upgrade=false, or remove it.
    6. Set dbms.mode=CORE in neo4j.conf to re-enable Causal Clustering in the configuration.
    7. Use neo4j-admin dump to make a copy of the database.
    8. Do not yet start the database.
  3. On each of the other Core servers:

    1. Delete the database directory (in a default configuration: data/databases/graph.db).
    2. Install Neo4j 3.4.7.
    3. Transfer any custom settings to the 3.4.7 installation, as prepared in the pre-upgrade step.
    4. If applicable, place the backed-up data/dbms directory into the data directory of the new instance.
    5. Perform neo4j-admin unbind on the instance.
    6. Using neo4j-admin load, restore the upgraded database onto this server.
  4. Startup all the Core Servers and see the cluster form.
  5. On each of the Read Replica servers:

    1. Stop Neo4j.
    2. Delete the database directory (in a default configuration: data/databases/graph.db).
    3. Install Neo4j 3.4.7.
    4. Transfer any custom settings to the 3.4.7 installation, as prepared in the pre-upgrade step.
    5. If applicable, place the backed-up data/dbms directory into the data directory of the new instance.
    6. Using neo4j-admin dump/load, restore the upgraded database onto this server. Alternatively, you can omit this step and let the Read Replica do a complete store copy.
    7. Start the Read Replica and see it join the cluster.