Migration checklist

This topic is about preparation steps for a Neo4j 3.5 DBMS migration to a Neo4j 4.0 DBMS.

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.

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, as well as the breaking changes between 3 and 4 MAJOR versions.

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.

Shut down the Neo4j DBMS

Because a migration requires the database to be offline, the first step is to cleanly shut down the Neo4j DBMS if it is still running:

bin/neo4j stop

or

systemctl stop neo4j

It is important to verify that the database shutdown process has finished successfully, and the database was cleanly shutdown. You can check the neo4j.log for these log messages for confirmation:

A sample log
2022-02-25 13:44:45.826+0000 INFO  Neo4j Server shutdown initiated by request
2022-02-25 13:44:45.830+0000 INFO  Stopped.

Back up your current deployment

You need to back up:

  • The neo4j.conf file.

  • All the files used for encryption, such as private key, public certificate, and the contents of the trusted and revoked directories (located in <neo4j-home>/certificates/).

  • The contents of <neo4j-home>/data/dbms (if there are any native users).

  • The Neo4j data store. If you are running a Debian/RPM distribution, you can skip this step.

For clusters deployments, you need to back up the contents of the /dbms folder and Neo4j data store only from one instance, which will be your elected instance.

(Direct path only) Backing up your existing 3.5.x store is optional. The direct path does not replace the current store but rather makes a copy of it and migrates it at the same time. Because of this, you will always have an available backup in case of disaster.

Because the database is now offline, you use the neo4j-admin dump command to create an offline backup (.dump file) of your data store:

$NEO4J_HOME/bin/neo4j-admin dump --to=$BACKUP_DESTINATION

The result is a file called <db_name>.dump located in $BACKUP_DESTINATION you have defined. This is the backup you are going to use for the migration. For more information about the neo4j-admin dump command, see Operations Manual → Back up an offline database.

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.

(Sequential path only) 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.

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, see (Migrate a single instance (offline) or Migrate a Causal Cluster (offline)).

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

For more information, see Operations Manual → Logging.