Prepare to migrate

This chapter provides a checklist of things to prepare before performing a migration from Neo4j version 3.5 to 4.0.

The supported upgrade path to Neo4j versions beyond 4.0 is 3.5.latest → 4.0.latest → 4.1 → 4.2. Please note that Neo4j versions 4.0 and beyond, requires Java 11.

Follow this checklist in order to ensure that you are well prepared before you start a production migration from Neo4j version 3.5 to 4.0:

Review Release Notes

To view the details of the changes that are included in each version, see the Release Notes.

Apply configuration changes

Prepare the contents of neo4j.conf to be used for the migrated database. If you are migrating a Causal Cluster, do this for each of the members in the cluster.

  1. Review the section Changes to other configuration settings and update all applicable configuration settings.

  2. It is also useful to inspect the current configuration file and take note of any non-default settings. When upgrading, it is particularly important to note any custom values of the settings dbms.directories.data and dbms.default_database. In cluster installations, pay attention to cluster-specific configuration settings, which may be different on different cluster members.

    Some configuration settings that have changed names are are automatically migrated to the new setting names during startup. When this happens, it is logged in neo4j.log. The automatic migration is not permanent, so if it is not changed in neo4j.conf, it will take place each time at startup. When the deprecated setting name are subsequently removed, unexpected problems may occur. It is therefore strongly recommended to update all relevant configuration settings at the time of the migration to 4.0.

Upgrade application code

Review the changes outlined in this guide and apply the necessary changes to your source code. How much development time is required to update the code will depend on the particular application. Make sure to test the application code thoroughly.

Upgrade custom plugins

Check the plugins directory to verify whether custom plugins are used in your deployment. Ensure that any plugins are compatible with Neo4j 4.x.

Plan disk space requirements

A migration requires substantial free disk space, as it makes an entire copy of the database. For the migration, make sure to make available an additional 50% * size_of(database directory). In a default configuration, the database directory is databases/neo4j, which is located in the data directory. In addition to this, do not forget to reserve the disk space needed for the pre-migration backup.

The migrated database may require slightly larger data files overall.

Perform a test migration

Based on the findings in this chapter, allocate a production-like 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, as well as potential additional action points, such as migration of plugins and application code.

Review the logs

The neo4j.log file contains valuable information on how many steps the migration will involve and how far it has progressed. For large migrations, it is a good idea to monitor this log continuously. Below is a sample of what the log may look like:

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