Migrate a single instance (offline)

This chapter describes the necessary steps to migrate a single instance from Neo4j version 3.5 to 4.0.

To migrate from 3.5.latest to a version beyond 4.0, the single instance must first be migrated to 4.0 and thereafter upgraded to the desired version.

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. If the Neo4j is running, shut it down cleanly.

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

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

  4. Set dbms.allow_upgrade=true to allow automatic store upgrade.

  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 single instance

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

    bin/neo4j start

    The migration takes place during startup.

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

4. Post-migration tasks

  1. When the upgrade finishes, open the neo4j.conf file and set dbms.allow_upgrade=false.

  2. Restart the instance.

  3. It is good practice to make a full backup immediately after the migration.