Migrate a standalone server (Helm)

This example shows how to migrate a standalone server deployed on Kubernetes with the neo4j/neo4j-standalone Helm chart from version 4.4 to 5.x.

Migration to Neo4j 5 is only supported from 4.4.

It is recommended to read the following pages before continuing:

The following example steps assume that Neo4j DBMS 4.4 is installed with the Helm release name standalone-4.

Prepare the 4.4 standalone server for migration

Prepare the 4.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 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 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 5.0 → Index configuration.

Steps

  1. 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)

  2. 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'}

  3. 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 each of your databases

  1. To ensure the databases do not get updated during the backup, put them into read-only mode using the Cypher command ALTER DATABASE <databasename> SET ACCESS READ ONLY.

  2. Create a directory to store backups. This tutorial uses /migration-backups.

  3. Backup each of your databases by choosing one of the options:

    • Enterprise Run the neo4j-admin backup command to back up all 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:

      		 
      kubectl exec -t -i standalone-4-0 -- neo4j-admin backup --database=*  --backup-dir=/backups --include-metadata=all

      Now copy the backups from the Kubernetes Pod to an intermediate to the /migration-backups folder on your local filesystem:

      kubectl cp standalone-4-0:/backups /path/to/migration-backups

      The result is a folder for each database, called <databasename> and located in the /tmp//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 → Backup an online database.

    • Use the neo4j-admin dump command to create an offline .dump file of the system and neo4j database.

      First place the Neo4j standalone server in offline maintenance mode:

      helm upgrade standalone-4 neo4j/neo4j-standalone --reuse-values --set neo4j.offlineMaintenanceModeEnabled=true

      Perform an offline dump of the databases:

      kubectl exec -t -i standalone-4-0 -- neo4j-admin dump --database=system --to=/backups
      kubectl exec -t -i standalone-4-0 -- neo4j-admin dump --database=neo4j --to=/backups

      Now copy the backups from the Kubernetes Pod to an intermediate to the /migration-backups folder on your local filesystem:

      kubectl cp standalone-4-0:/backups /path/to/migration-backups

      The result is two files called system.dump and neo4j.dump located in the /migration-backups folder. For more information about the neo4j-admin dump command, see Operations Manual → Backup an offline database.

      The file system copy-and-paste of databases is not supported and may result in unwanted behavior.

Set up 5.x standalone server

Follow the Quickstart guide for detailed information about installing a 5.x standalone server using the neo4j/neo4j Helm chart.

Prepare the 5.x standalone server for the migration

  1. Update the neo4j helm repository:

    helm repo update neo4j

  2. Make a note of any user-supplied values that need to be migrated from the 4.4 Helm installation. The user-supplied values can be printed out using the command:

    helm get values standalone-4

  3. After reading the Quickstart guide, install a Neo4j 5.x standalone server, for example:

    helm install standalone-5 neo4j/neo4j --set volumes.data.mode=defaultStorageClass --set neo4j.name=standalone-5 --set neo4j.password=password

    If you are using TLS and want to reuse the keys from the 4.4 installation, install 5.x in the same namespace as 4.4.

Restore the database backups

Migrate your databases using one of the following options depending on the Neo4j edition:

Enterprise

  1. Copy the backup files from the /migration-backups to the 5.x standalone server:

    kubectl cp /path/to/migration-backups/<databasename> standalone-5-0:/backups/<databasename>

  2. If restoring the default neo4j database or another database that already exists, it must first be dropped:

    kubectl exec -t -i standalone-5-0 -- cypher-shell -u neo4j -p password "DROP DATABASE neo4j IF EXISTS"

  3. Use the neo4j-admin restore command to restore each of your databases except the system database:

    kubectl exec -t -i standalone-5-0 -- neo4j-admin database restore <databasename> --from-path=/backups/<databasename>

  4. Migrate each of your restored databases:

    kubectl exec -t -i standalone-5-0 -- neo4j-admin database migrate <databasename>

  5. Recreate each of your migrated databases:

    kubectl exec -t -i standalone-5-0 -- cypher-shell -d system -u neo4j -p password "CREATE DATABASE <databasename>"

  6. (Optional) Restore the roles and privileges associated with each of your databases by running the respective metadata script data/databases/databasename/tools/metadata_script.cypher, which the neo4j-admin restore command output, using Cypher Shell:

    kubectl exec -t -i standalone-5-0 -- cypher-shell -u neo4j -p password -d system --param "database => 'neo4j'" -f data/databases/databasename/tools/metadata_script.cypher

  7. If you have kept your 4.4 server running while setting up the new one, you can uninstall it now.

  1. Place the service in offline maintenance mode, so the Neo4j process is not running:

    helm upgrade standalone-5 neo4j/neo4j --reuse-values --set neo4j.offlineMaintenanceModeEnabled=true

  2. Copy the backup files from the /migration-backups to the 5.x standalone server:

    kubectl cp /path/to/migration-backups/<databasename>.dump standalone-5-0:/backups/<databasename>.dump

  3. Use the neo4j-admin database load command to move the dump files to the new installation:

    kubectl exec -t -i standalone-5-0 -- neo4j-admin database load --overwrite-destination --from-path=/backups/<databasename>.dump "*"

  4. Migrate all your databases:

    kubectl exec -t -i standalone-5-0 -- neo4j-admin database migrate "*"

  5. Place the Neo4j DBMS in online mode:

    helm upgrade standalone-5 neo4j/neo4j --reuse-values --set neo4j.offlineMaintenanceModeEnabled=false

  6. If you have kept your 4.4 server running while setting up the new one, you can uninstall it now.