Migrate a standalone server (Docker)

This example shows how to migrate a v4.4 standalone server running on Docker to v5.x.
Migration to Neo4j v5 is supported only from version v4.4.

It is recommended to read the following pages before continuing:

The following example steps assume that Neo4j DBMS v4.4 is running in a Docker container named neo4j-4.4, with the /data directory in the container mapped to the /4.4/data on the host machine. The backups port must be exposed on the container so that it can be backed up. Ports cannot be exposed after the container has already started. By default, this is port 6362.
If you want to monitor the logs, you should also map the container’s /logs directory to a /logs directory on the host machine.

An example of a docker run command to spin up Neo4j Enterprise

docker run -d \
    --name=neo4j-4.4 \
    --publish=7474:7474 --publish=7687:7687 --publish=6362:6362 \
    --volume=/path/to/4.4/data:/data \
    --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    neo4j:4.4.x-enterprise

Prepare the v4.4 standalone server for migration

Prepare the v4.4 standalone server for migration by recreating the indexes and the index-backed constraints to match the new index types, and by backing up each of your databases.

Recreate indexes and index-backed constraints

In v5.0, the BTREE index type is no longer available. Therefore, it is recommended to recreate all your BTREE indexes and index-backed constraints with index providers native-btree-1.0 or lucene+native-3.0 before switching to v5.x. During the migration, v5.x checks whether each BTREE index and index-backed constraint has an equivalent type of index and provider, and drops them.

What type of index to use instead of BTREE?

In most cases, RANGE indexes can replace BTREE. However, there might be occasions when a different index type is more suitable, such as:

Use POINT indexes if the property value type is point and distance or bounding box queries are used for the property.
Use TEXT indexes if the property value type is text and the values can be larger than 8Kb.
Use TEXT indexes if the property value type is text and CONTAINS and ENDS WITH are used in queries for the property.

If more than one of the conditions is true, it is possible to have multiple indexes of different index types on the same schema. For more information on each index type, see Operations Manual v5.0 → Index configuration.

Steps

Recreate each of your BTREE indexes on the same schema but using the new type (RANGE, POINT, or TEXT) as per your use case. The following example creates a range index on a single property for all nodes with a particular label:
```
CREATE RANGE INDEX range_index_name FOR (n:Label) ON (n.prop1)
```
Recreate each of your index-backed constraints with index providers native-btree-1.0 or lucene+native-3.0 on the same schema but with the new provider. The following example creates a unique node property constraint on a single property for all nodes with a particular label. The backing index is of type range with range-1.0 index provider.
```
CREATE CONSTRAINT constraint_with_provider FOR (n:Label) REQUIRE (n.prop1) IS UNIQUE OPTIONS {indexProvider: 'range-1.0'}
```
Run SHOW INDEXES to verify that the indexes have been populated and constraints have been created with the correct index provider.

For more information about creating indexes, see Cypher Manual → Creating indexes.

Backup all your databases

Create a directory to store backups. This tutorial uses /migration-backups.
Set the neo4j user as the owner of /migration-backups to allow write access from the Neo4j docker container:
```
sudo chown neo4j:neo4j /path/to/migration-backups
```
Processes in the Neo4j docker container run under the neo4j user by default.

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

All databases that you want to back up must be online.
Use the option --include-metadata=all to include all roles and users associated with each of your databases.
Neo4j admin must be the same version as the current database, not the version being upgraded to.

docker run -it --rm \
   --network container:neo4j-4.4 \
   --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
   -v /path/to/4.4/data:/data \
   -v /path/to/migration-backups:/backups \
   neo4j:4.4.x-enterprise \
      neo4j-admin backup \
        --database "*" \
        --backup-dir /backups \
        --include-metadata all

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 the backup directory _migration-backups/databasename/tools/metadata_script.cypher. For more information about the neo4j-admin backup command, see Operations Manual → Back up an online database.

Stop Neo4j v4.4:
```
docker stop neo4j-4.4
```

Set up v5.x standalone server

Prepare the v5.x standalone server for the migration

Start Neo4j v5.x with the /data directory in the container mapped to /5.x/data on the host machine.

docker run -d \
    --name=neo4j-5.x \
    --publish=7474:7474 --publish=7687:7687 --publish=6362:6362 \
    --volume=/path/to/5.x/data:/data \
    --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    neo4j:5.x-enterprise

Migrate the v4.4 configuration file to a v5.x-compatible format.

The Neo4j Admin commands must be invoked with the same user as Neo4j runs as. By default, this user is called neo4j. This guarantees that Neo4j will have full rights to start and work with the database files you use.

docker run -it --rm \
    --network container:neo4j-5.x \
    --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    --volume=/path/to/4.4/conf:/conf \
      neo4j:5.x-enterprise \
      neo4j-admin \
          server migrate-configuration

Verify that the configuration file looks as expected.

It is recommended to read up on the new v5.x settings to fully take advantage of the v5.x features.

Migrate the database backups

Use the neo4j-admin restore command to restore each of your databases (except system) into the new location:

Assuming that neo4j is the default database and you want to restore the v4.4 neo4j database backup, first, you need to run DROP DATABASE neo4j IF EXISTS.

docker run -it --rm \
    --network container:neo4j-5.x \
    --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    -v /path/to/5.x/data:/data \
    -v /path/to/migration-backups:/backups \
       neo4j:5.x-enterprise \
       neo4j-admin \
           database restore \
           --from-path=/backups/<databasename> \
           <databasename>

Migrate each of your restored databases:

docker run -it --rm \
    --network container:neo4j-5.x
    -v /path/to/5.x/data:/data \
    --env=NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
    neo4j:5.x-enterprise \
    neo4j-admin \
        database migrate <databasename>

Use docker exec --interactive --tty neo4j-5.x cypher-shell -u neo4j -p neo4j to use Cypher Shell.
Run the following command for each of your migrated databases to activate them:
```
CREATE DATABASE <databasename>;
```
Change the active database to the created one:
```
:use database <databasename>;
```
Run SHOW INDEXES to verify that the indexes and constraints are of the correct type and with the correct index provider.
(Optional) Restore the roles and privileges associated with each of your databases by running the respective metadata script data/scripts/databasename/restore_metadata.cypher, which the neo4j-admin restore command output, using Cypher Shell:
```
cat /path/to/data/scripts/databasename/restore_metadata.cypher | docker exec --interactive <containerID/name> cypher-shell -u neo4j -p <password> -d system --param "database => 'databasename'"
```

Was this page helpful?