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.
Ensure that you have completed all tasks on the Migration checklist.
Verify that you have shut down the Neo4j DBMS. You can check the neo4j.log.
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.
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.
dbms.allow_upgrade=trueto allow automatic store upgrade.
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.conffile 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
systemdatabase on the first startup of the Neo4j 4.0 DBMS.
If you are using custom plugins, make sure they are updated and compatible with the new version, and place them in the /plugins directory.
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>.
Move the backup file into the new installation by running the
neo4j-admin loadcommand from
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
With the backup in-place, initiate the data migration by starting Neo4j 4.0:
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.
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 DATABASEcommand in the Browser or Cypher Shell:
CREATE DATABASE name
When the upgrade finishes, open the neo4j.conf file and set
Restart the instance.
It is good practice to make a full backup immediately after the migration.