Migrate a cluster (Docker)
This example shows how to migrate a 4.4 cluster to 5.x.
Migration to Neo4j 5 is supported only from version 4.4.
It is recommended to read the following pages before continuing: |
The following example steps are based on the following pre-upgrade state:
-
The environment has three Primary members located on three different servers a, b, c.
-
Neo4j DBMS 4.4 is running in a Docker container on each server with /data directory in the container mapped to /opt/data on the host machine and the container is named
neo4j-dbms
. You can achieve this, for instance, by running the following command on each server:docker run -d \ --name=neo4j-dbms \ --volume=/opt/data:/data \ neo4j:4.4-enterprise
Prepare your indexes and index-backed constraints for migration
Prepare the 4.4 cluster 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.
In 5.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 5.x.
During the migration, 5.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
anddistance
orbounding 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
andCONTAINS
andENDS 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 5.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
orlucene+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 withrange-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.
Migration steps
On server a
-
Run
SHOW DATABASES YIELD *
to ensure that all databases are up-to-date with the last committed transactions. Databases can be put into read-only mode if needed using the Cypher commandALTER DATABASE database-name SET ACCESS READ ONLY
. -
Create a directory to store backups. This tutorial uses /opt/migration-backups.
-
Set the
neo4j
user as the owner of /opt/migration-backups to allow write access from the Neo4j docker container:sudo chown neo4j:neo4j /opt/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.
docker run -i -t --rm -v /opt/data:/data neo4j:4.x-enterprise neo4j-admin backup --database * --backup-dir /opt/migration-backups --include-metadata all
The result is a folder for each database, called <databasename> and located in the /opt/migration-backups folder, and a metadata script for each database, located in the backup directory data/scripts/databasename/restore_metadata.cypher. For more information about the
neo4j-admin backup
command, see Operations Manual → Back up an online database. -
On each server
-
Stop Neo4j 4.4:
docker stop neo4j-dbms
-
Start Neo4j 5.x:
docker run -d --name neo4j-dbms -v /opt/data:data neo4j:5.x-enterprise
5.x.y is expected to have no stores installed.
On server a
-
Run
DROP DATABASE neo4j
(assuming thatneo4j
is the default database). -
Use the
neo4j-admin restore
command to restore theneo4j
database:docker run -i -t --rm -v /opt/data:/data neo4j:5.x-enterprise neo4j-admin database restore --from /opt/migration-backups/neo4j --database neo4j --move
-
Migrate the
neo4j
database:docker run -i -t --rm -v /opt/data:/data neo4j:5.x-enterprise neo4j-admin database migrate --database neo4j
-
Repeat steps 2 and 3 for every backup in /opt/migration-backups directory except for the
system
database. -
Run
SHOW SERVERS
to retrieve the server ID for server a. -
Run the following command for each of your migrated databases to activate them:
CREATE DATABASE neo4j OPTIONS {existingData: 'use', existingDataSeedInstance: '[ServerId for a]'}
-
(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:Usingcat
(UNIX)cat data/scripts/databasename/restore_metadata.cypher | bin/cypher-shell -u user -p password -a ip_address:port -d system --param "database => 'databasename'"
Usingtype
(Windows)*type data\scripts\databasename\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => 'databasename'"
-
Run
REALLOCATE DATABASES
to evenly distribute your databases among the servers.
Monitor the logs
The neo4j.log file contains information on how many steps the upgrade will involve and how far it has progressed.
Neo4j logging output is written to files in the /logs directory. This directory is mounted as a /logs volume.
Was this page helpful?