Migrate a Causal Cluster (offline)

This chapter describes the necessary steps to migrate a Causal Cluster from Neo4j version 3.5 to 4.0.

The migration of a Causal Cluster from Neo4j version 3.5 to 4.0 requires downtime. Therefore, it is recommended to perform a test migration in a production-like environment to get information on the duration of the downtime.

To migrate from 3.5.latest to a version beyond 4.0, the cluster must first be migrated to 4.0 and thereafter upgraded to the desired version. For more information, see Supported upgrade and migration paths.

The prerequisites and the migration steps must be completed for each cluster member.

1. Prerequisites

  1. Verify that you have installed Java 11.

  2. Review the new features and improvements that have been carried out in the new version. See the Neo4j 4.0 changelog and Release Notes.

  3. Ensure that you have completed all tasks on the Migration checklist.

2. Prepare for the migration

  1. Shut down all the cluster members (Cores and Read Replicas).

  2. Perform neo4j-admin unbind on each cluster member to remove cluster state data.

  3. Install the Neo4j version that you want to migrate to on each instance. For more information on how to install the distribution that you are using, see Operations Manual v4.0 → Installation.

  4. Update the neo4j.conf file as per the notes that you have prepared for each instance in section Prepare a new neo4j.conf file to be used by the new installation.

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

  6. Restore your database in the new installation using neo4j-admin load (offline).

    If your old installation has modified configurations starting with dbms.directories.* or the setting dbms.active_database, verify that the new neo4j.conf file is configured properly to find these directories.

    The migration of users and roles from 3.5 to 4.0 is done automatically. Therefore, you do not have to move the data/dbms/ directory and contents to the new installation. The files in 3.5 will be parsed and the content added to the system database on the first startup of the Neo4j 4.0 DBMS.

  7. If using custom plugins, make sure they are updated and compatible with the new version, and place them in the /plugins directory.

  8. Apply all necessary changes to your applications' source code. How much development time is required to update the code depends on the particular application. Make sure to test the application code thoroughly.

3. Migrate your cluster

On one of the Cores
  1. Open the neo4j.conf file of the new installation and configure the following settings:

  2. Start Neo4j by running the following command from <neo4j-home>:

    bin/neo4j start

    The migration takes place during startup.

  3. Monitor the neo4j.log file for information on how many steps the migration involves and how far it has progressed.

  4. When the migration finishes, stop the server.

  5. Open the neo4j.conf file and configure the following settings:

  6. Use neo4j-admin dump to make a dump of each of your databases and transactions, including the system database.

  7. Do not yet start the server.

On each of the other Cores
  1. Copy the database dumps you created on the first Core server to each of the other Cores.

  2. Use neo4j-admin load --from=<archive-path> --database=<database> --force to replace each of your databases, including the system database, with the ones you migrated on the first Core server.

  3. Start each of the core servers, including the first one, and verify that they join in a cluster.

For each Read Replica

Start the Read Replica and wait for it to catch up with the rest of the cluster members.

(Optional) While an empty read replica will eventually get a full copy of all data from the other members of your cluster, catching up may take some time. To speed up the process, you can load the data first by using neo4j-admin load --from=<archive-path> --database=<database> --force to replace each of your databases with the migrated one.

Verify that the Read Replicas join the cluster.

4. Post-migration

It is recommended to perform a full backup, using an empty target directory.