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:
-
Complete all prerequisites for the migration.
-
Reserve enough disk space for the pre-migration backup and the migration.
-
Shut down the Neo4j DBMS that you want to migrate.
-
Back up your current deployment to avoid losing data in case of a failure.
-
Download the new version of Neo4j. Make sure the migration path is supported.
-
Prepare a new neo4j.conf file to be used by the new installation.
-
Perform a test migration as per your Neo4j version and deployment type (Migrate a single instance (offline) or Migrate a Causal Cluster (offline)).
-
Perform the migration.
If you are migrating a Causal Cluster, complete the checklist for each cluster member. |
Prerequisites
-
Verify that you have installed Java 11.
-
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:
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.*
anddbms.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 |
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.
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.