Migrate your databases

The following steps assume that:

  • You have one or more databases hosted on Neo4j v4.4

  • You have installed an equivalent Neo4j v5 DBMS to move the databases to.

Prepare the databases for migration

Confirm that BTREE indexes have RANGE, POINT or TEXT equivalents

It is recommended that you create new RANGE, POINT, or TEXT indexes for each of your BTREE indexes and index-backed constraints. See the instructions in Prepare indexes

Make your databases read-only

To ensure the databases do not get updated during the backup, put them into read-only mode using Cypher:

ALTER DATABASE <databasename> SET ACCESS READ ONLY

Create a backup of each database

You can back up all databases from a single v4.4 cluster member.

If you are migrating databases from an installation of Neo4j v4.4 Community Edition, you will need to take the database offline and perform a backup using the neo4j-admin dump command.

If you are backing up a database from a cluster, run the Cypher command SHOW DATABASES YIELD *, and choose a server that is up-to-date with the last committed transaction on all databases as a backup source.

  1. Create a directory to store backups. These steps use /migration-backups.

  2. Run the neo4j-admin backup command to back up each of your databases.

Use the option --include-metadata=all to include all roles and users associated with each of your databases.

/usr/bin/neo4j-admin backup --database=<databasename>  --backup-dir=/migration-backups --include-metadata=all

Ensure that you have successfully backed up all your databases. The result is a folder for each database, called <databasename> and located in the /migration-backups folder, and a metadata script for each database, located in migration-backups/databasename/tools/metadata_script.cypher.

For more information about the neo4j-admin backup command, see Operations Manual v4.4 → Back up an online database.

Switching to Neo4j v5

The Neo4j v4.4 DBMS can now be shutdown. You may prefer to leave it online in read-only mode until the migration is complete.

From this point on we’ll be working 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.

Make sure Neo4j v5 doesn’t already host any databases with the same name as those that you will 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 will need to restore your dump-file using the neo4j-admin database load command.

  1. 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>
  2. 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 --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 to understand the consequences.

Recreate the databases

Start Neo4j v5 and recreate each of your databases using the following Cypher:

CREATE DATABASE <databasename>
  1. 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 using ALTER DATABASE.

    For more information, see Operations Manual v5 → Create Database.

  2. 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]'}
  3. Finally, run REALLOCATE DATABASES to distribute your databases among the servers.

    REALLOCATE DATABASES

(Optional) Restore roles and privileges

Restore the roles and privileges associated with each of your databases by running 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-enterprise-5.x/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-enterprise-5.x\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.