Upgrade a Causal Cluster
Enterprise Edition

Important pre-upgrade information

All upgrades should be approached with careful planning and testing.

Pre-upgrade steps

  1. Read Upgrade planning thoroughly and perform all the steps listed there.

  2. Perform and verify backups:

    • Back up neo4j.conf.

    • If using native user and role management, back up the data/dbms directory.

    • Back up all the files used for encryption, i.e. private key, public certificate, and the contents of the trusted and revoked directories. The locations of these are described in SSL framework. You should back up these files on each server in the cluster.

    • Verify that you have a full backup that is stored in a safe location.

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

  4. If using custom plugins, make sure that you have the plugins that are adjusted for the new version in an accessible location.

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

Rolling upgrade

Limitations

Rolling upgrades are only supported between patch releases, and only when a store format upgrade is not needed. Read the Data Store Changes page 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.

Recommendations

  • When upgrading a cluster, it is important to do so in a systematic, predictable way. The critical point during the upgrades is knowing when to switch off the original members. It is recommended that you use the status endpoint when performing a rolling upgrade, which provides access to information that can aid you when deciding which member to switch off, and when it is safe to do so. For more information, see Status endpoint.

    It is only possible to use the status endpoint when upgrading from Neo4j v3.5, since that is when the status endpoint was introduced.

  • Since replacing cores is no different from temporarily removing cores, the process of doing a rolling upgrade reduces fault tolerance temporarily. If you absolutely need to maintain a minimum threshold of fault tolerance, then you should increase the cluster size to account for this planned failure.

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. (Optional/Recommended) Use the status endpoint to evaluate whether it is safe to remove this member.

    2. Shutdown the instance.

    3. Install Neo4j using one of the following methods, specific to your technology:

      • If using a tarball or zipfile for installation:

        1. Untar or unzip the version of Neo4j that you want to upgrade to.

        2. Place the neo4j.conf file, that you have prepared for this server, into the Configuration directory.

        3. If using native user and role management, copy the data/dbms directory into the new location.

        4. Copy the files used for encryption from the old installation to the new one.

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

        6. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

      • If using a Debian or RPM distribution:

        1. Install the version of Neo4j that you want to upgrade to.

        2. When prompted, review the differences between the neo4j.conf files of the previous version and the new version of Neo4j. Transfer any custom settings to the new installation, as prepared in the pre-upgrade step.

        3. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

    4. Start up Neo4j, and see it join the cluster.

  2. Repeat the previous steps for every server instance.

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 the version of Neo4j that you want to upgrade to.

  2. Use the new neo4j.conf that you have prepared in the pre-upgrade step.

  3. If using native user and role management, place the backed-up data/dbms directory into the data directory of the new instance.

  4. Copy the files used for encryption from the old installation to the new one.

  5. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory on the new instance.

  6. Start up the new instance, and let it complete a store copy.

  7. See the new instance join the cluster.

  8. (Optional/Recommended) Use the status endpoint to evaluate whether it is safe to remove an old member.

  9. Shutdown the old instance.

  10. Repeat the previous steps for every server instance.

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 the version of Neo4j that you want to upgrade to.

        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. If using native user and role management, place the backed-up data/dbms directory into the data directory of the new instance.

        5. Copy the files used for encryption from the old installation to the new one.

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

        7. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

      • If using a Debian or RPM distribution:

        1. Set dbms.allow_upgrade=true in neo4j.conf.

        2. Install the version of Neo4j that you want to upgrade to.

        3. When prompted, review the differences between the neo4j.conf files of the previous version and the new version of Neo4j. Transfer any custom settings to the new 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.

        4. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

    3. Start up Neo4j. The database upgrade will take place during startup.

      The neo4j.log file contains valuable information on how many steps the upgrade will involve and how far it has progressed. For large upgrades, it is a good idea to monitor this log continuously.

    4. Stop your Neo4j database once again.

    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 restart 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 the version of Neo4j that you want to upgrade to.

    3. Transfer any custom settings to the new installation, as prepared in the pre-upgrade step.

    4. If using a tarball or zipfile for installation:

      • If using native user and role management, place the backed-up data/dbms directory into the data directory of the new instance.

      • Copy the files used for encryption from the old installation to the new one.

    5. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

    6. Perform neo4j-admin unbind on the instance.

    7. 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 the version of Neo4j that you want to upgrade to.

    4. Transfer any custom settings to the new installation, as prepared in the pre-upgrade step.

    5. If using a tarball or zipfile for installation:

      • If using native user and role management, place the backed-up data/dbms directory into the data directory of the new instance.

      • Copy the files used for encryption from the old installation to the new one.

    6. If using custom plugins, place the plugins that are adjusted for the new version in the /plugins directory.

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

    8. Start the Read Replica and see it join the cluster.