Migration checklist

This chapter describes how to prepare to migrate Neo4j from an earlier major version.

Before you start preparing for migration, it is very important to read the information in Understanding upgrades and migration and Supported upgrade and migration paths.

Follow the checklist to prepare for migrating your Neo4j deployment:

If you are migrating a Causal Cluster, complete the checklist 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. Reserve enough disk space

A migration requires substantial free disk space, as it makes a complete copy of the database. Therefore, it is essential to make available an additional 50% * the size of your database directory. In a default configuration, the database directory is databases/neo4j, which is located in the data directory. The migrated database may require slightly larger data files overall.
You must also reserve the disk space needed for the pre-migration backup.

3. Back up your current deployment

Back up your database using the command neo4j-admin dump. For more information, see Operations Manual → Back up an offline database.

Migrating Neo4j 3.5 to version 4.0 requires downtime.

4. Prepare a new neo4j.conf file to be used by the new installation

A Neo4j migration requires changes to the configuration. Therefore, you have to prepare a new neo4j.conf file to be used by the new deployment. If you are migrating a Causal Cluster, do this for each cluster member.

  • Update the new neo4j.conf file with any non-default settings from your old installation.

  • Note any custom values of the settings dbms.directories.* and dbms.active_database.

  • In cluster installations, pay attention to cluster-specific configuration settings, which might be different for the different cluster members.

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.

5. Perform a test migration

Based on the findings in this chapter, allocate a staging test environment for the migration and do a test migration. The test migration will give you valuable information about the time required for the production migration. Follow the steps as per your Neo4j version and deployment type.

6. Monitor the logs

The neo4j.log file contains information on how many steps the migration involves and how far it has progressed. For large migrations, it is a good idea to monitor this log continuously.

A sample log
2018-09-18 13:24:23.243+0000 INFO  Starting...
2018-09-18 13:24:24.262+0000 INFO  Initiating metrics...
2018-09-18 13:24:24.488+0000 INFO  Starting upgrade of database
2018-09-18 13:24:24.538+0000 INFO  Migrating Indexes (1/5):
2018-09-18 13:24:24.542+0000 INFO    10% completed
2018-09-18 13:24:24.543+0000 INFO    20% completed
2018-09-18 13:24:24.543+0000 INFO    30% completed
...
...
...
2018-09-18 13:24:24.574+0000 INFO  Migrating Counts store (5/5):
2018-09-18 13:24:24.574+0000 INFO    10% completed
2018-09-18 13:24:24.574+0000 INFO    20% completed
2018-09-18 13:24:24.575+0000 INFO    30% completed
...
...
...
2018-09-18 13:24:24.576+0000 INFO    100% completed
2018-09-18 13:24:24.584+0000 INFO  Successfully finished upgrade of database