Migrate your databases

The following steps assume that:

You have taken backups of any Neo4j 4.4 databases you want to migrate.
You have installed an equivalent Neo4j 5 DBMS to move the databases to.

Switching to Neo4j 5

If your method of installation (e.g. tarball or docker) allows you to have Neo4j 4.4 and 5 installations concurrently on the same server, you may now shut down your Neo4j 4.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 5 DBMS. If both versions are on the same machine, you may need to change the default Java runtime to Java 17. From version 5.14, Neo4j also supports Java 21.

The Neo4j Database 5.26 LTS is the last version that will use the Java SE 17 Platform. It is recommended to move to Java SE 21, which is supported with the Neo4j Database 5.14 onwards.

Make sure Neo4j 5 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 5

You can now restore the database backups to Neo4j 5.

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 4.4 Community Edition, you need to restore your dump file using the neo4j-admin database load command.

For more information, see Operations Manual 5 → Restore a database dump.

Use the neo4j-admin restore command to restore each of your databases, except the system 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 5 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 --force-btree-indexes-to-range to force neo4j-admin database migrate to drop the BTREE indexes and replace them with RANGE indexes. It is advisable to read the section on preparing indexes from Prepare for your migration to understand the consequences.

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 5 → Copy a database store.

Recreate the databases

Start Neo4j 5 and recreate each of your databases using the following Cypher^®:

CREATE DATABASE <databasename>

Start Neo4j 5 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 5 cluster you can optionally use the TOPOLOGY parameter to specify how many primary and secondary copies are required. These values can be changed later using ALTER DATABASE.

For more information, see Operations Manual 5 → 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 run REALLOCATE DATABASES to make the cluster re-balance databases across all servers that are part of the cluster.
```
REALLOCATE DATABASES
```
For more information, see Operations Manual 5 → Reallocate databases.

Recreate database aliases

If you are using database aliases, you must recreate them manually. For more information on aliases, see Operations Manual → Managing database aliases for standard databases.

Restore roles and privileges

You can restore the roles and privileges associated with each of your databases using their metadata script that was created when you backed up your databases in section Create a backup of each database. The metadata scripts are located in _migration-backups/<databasname>/tools/metadata_script.cypher. Run the respective metadata script using Cypher Shell:

Using cat (UNIX):

cat migration-backups/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 migration-backups\data\scripts\<databasename>\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => '<databasename>'"

If you have not used the --include-metadata=all option when creating the backup, you will need to recreate the roles and privileges manually. For more information, see Operations Manual 5 → Manage roles and Operations Manual 5 → Built-in roles and privileges.

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.