Migrate a single instance

This chapter describes the necessary steps to migrate a single instance from Neo4j 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.

Prerequisites

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

Prepare for the migration

  1. Verify that you have shut down the Neo4j DBMS. You can check the neo4j.log.

  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. Replace the neo4j.conf file with the one 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 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/).

    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.

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

Migrate the data and start the server

Before migrating the data, you have to move the backup file to the /data directory of Neo4j 4.0.

This step is not applicable if you have dbms.directories.data pointing to a directory outside of <neo4j-home>.

  1. Move the backup file into the new installation by running the neo4j-admin load command from <neo4j-home>:

    It is a requirement to use this command as file system copy-and-paste of databases is not supported and may result in unwanted behaviour. If you are running a Debian/RPM distribution, you can skip this step.

    		 
    bin/neo4j-admin load --from=$BACKUP_DESTINATION/<db_name>.dump –database=<db_name> --force

  2. With the backup in-place, initiate the data migration by starting Neo4j 4.0:

    bin/neo4j start

    or

    systemctl start neo4j

    The database migration takes place during startup. Your indexes are also automatically migrated to the most recent index provider during startup. However, indexes require populating after migration. Your queries will not be able to use the indexes while they are populating so you may see a temporary performance hit. If your queries are 100% dependent on some indexes, it is advisable to account for index population as part of the duration of the migration.

    The neo4j.log file contains valuable information on how many steps the migration involves and how far it has progressed. Index populations are tracked on the debug.log. For large migrations, it is a good idea to monitor these logs continuously.

  3. If you used a different database name than what is set as the default database in neo4j.conf, you need to activate that database before being able to use it. You can do this with the CREATE DATABASE command in the Browser or Cypher® Shell:

    CREATE DATABASE name

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.