Migrate your databases
The following steps assume that:
-
You have taken backups of any Neo4j v4.4 databases you want to migrate.
-
You have installed an equivalent Neo4j v5 DBMS to move the databases to.
Switching to Neo4j v5
If your method of installation (e.g. tarball or docker) allows you to have Neo4j v4.4 and v5 installations concurrently on the same server, you may now shut down your Neo4j v4.4 process. Alternatively, you may prefer to leave it running, with all its databases in read-only mode until the migration is complete.
If you do choose to run two Neo4j installations concurrently, ensure that your server has sufficient resources to support this and that your configuration for the two installations does not conflict (e.g., on ports). |
From this point on, you are on the Neo4j v5 DBMS. If both versions are on the same machine, you may need to change the default Java runtime to Java 17.
Make sure Neo4j v5 does not already host any databases with the same name as those that you want to migrate (ignoring the system
database).
Restore the database on Neo4j v5
You can now restore the database backups to Neo4j v5.
If you are migrating to a cluster, only restore them to one server; later you will use this server to seed the others.
If you are migrating databases from an installation of Neo4j v4.4 Community Edition, you need to restore your dump file using the For more information, see Operations Manual v5 → Restore a database dump. |
-
Use the
neo4j-admin restore
command to restore each of your databases, except thesystem
database:/usr/bin/neo4j-admin database restore <databasename> --from-path=/migration-backups/<databasename>
-
Use the
neo4j-admin database migrate
command to update the file metadata to the v5 format:/usr/bin/neo4j-admin database migrate <databasename>
The command will fail if you do not have RANGE, POINT, or TEXT indexes for each of your BTREE indexes and index-backed constraints.
You can use the option |
If you also want to compress your databases when moving to 5.x, store copy can be used as an alternative to migrate a database between 4.4 and 5.x. For more information, see Operations Manual v5 → Copy a database store. |
Recreate the databases
Start Neo4j v5 and recreate each of your databases using the following Cypher:
CREATE DATABASE <databasename>
-
Start Neo4j v5 and retrieve the server ID for the server where you restored the backups by running:
SHOW SERVERS YIELD address, serverId
When you create a database on a Neo4j v5 cluster you can optionally use the
TOPOLOGY
parameter to specify how many primary and secondary copies are required. These values can be changed later usingALTER DATABASE
.For more information, see Operations Manual v5 → Create Database.
-
Recreate each of your databases using the following Cypher:
CREATE DATABASE <databasename> TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES OPTIONS {existingData: 'use', existingDataSeedInstance: '[ServerId for a]'}
-
(Optional) Each
CREATE DATABASE
allocates the databases, but this may result in an unbalanced distribution. You can runREALLOCATE DATABASES
to make the cluster re-balance databases across all servers that are part of the cluster.REALLOCATE DATABASES
For more information, see Cypher Manual v5 → Server Management - Reallocate.
(Optional) Restore roles and privileges
You can restore the roles and privileges associated with each of your databases in case you first performed a backup including the metadata.
This can be achieved by using the command --include-metadata=none|all|users|roles
.
For more information about this procedure, see Back up an online database.
In case you already performed this action, run the respective metadata script data/scripts/<databasename>/restore_metadata.cypher, with the neo4j-admin restore
command output, using Cypher Shell:
Using cat
(UNIX):
cat $NEO4J_HOME/data/scripts/<databasename>/restore_metadata.cypher | bin/cypher-shell -u user -p password -a ip_address:port -d system --param "database => '<databasename>'"
Using type
(Windows):
type $NEO4J_HOME\data\scripts\<databasename>\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => '<databasename>'"
Monitor the logs
When Neo4j starts, it can be useful to monitor the logs for any errors or warnings caused by the migration. You can find information about the upgrade in the neo4j.log file.
Was this page helpful?