Migrate a standalone server (TAR/ZIP)

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

It is recommended to read the following pages before continuing:

The following example steps assume that the Neo4j v4.4 version is running with its binaries, config file, and data in the default locations.

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

  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.

      • The command must be invoked as the neo4j user to ensure the appropriate file permissions.

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

      		 
      /neo4j-enterprise-4.4/bin/neo4j-admin backup --database=*  --backup-dir=/path/to/migration-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 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.

      /neo4j-community-4.4/bin/neo4j-admin dump --database=system  --to=/path/to/migration-backups
      /neo4j-community-4.4/bin/neo4j-admin dump --database=neo4j  --to=/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.

  4. Stop the Neo4j DBMS.

    Alternatively, if you are using the Enterprise edition, you can postpone the downtime of your v4.4 standalone server until the very end if you can prepare the v5.x standalone on a separate server or make sure the ports do not conflict. This way, the databases in the v4.4 Neo4j DBMS will be available in READ ONLY mode while you prepare the new DBMS.

    		 
    neo4j-enterprise-4.4/bin/neo4j stop

Set up v5.x standalone server

Prepare the v5.x standalone server for the migration

  1. Make sure that you are using Java 17.

  2. Download v5.x TAR or ZIP from Neo4j Download Center and unpack it.

  3. Copy the neo4j.conf file from the v4.4 installation and paste it into the /conf directory of the v5.x installation to replace its neo4j.conf file.

  4. Migrate the 4.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.

    		 
    /bin/neo4j-admin server migrate-configuration

  5. 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.

  6. Copy all the files used for encryption, such as private key, public certificate, and the contents of the trusted and revoked directories from /neo4j-enterprise-4.4/certificates/ to /neo4j-enterprise-5.x/certificates.

  7. If you are using custom plugins, make sure they are updated and compatible with Java 17, and place them in the /plugins directory.

Migrate the database backups

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

Enterprise Edition

  1. (Optional) Set the initial password:

    If this step is skipped, the new Neo4j database will have the default password neo4j.

    		 
    /neo4j-enterprise-5.x/bin/neo4j-admin dbms set-initial-password <password>

  2. Start Neo4j v5.x:

    /neo4j-enterprise-5.x/bin/neo4j start

    v5.x is expected to have no stores installed.

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

    If you want to restore an old neo4j database and it is the default, run DROP DATABASE neo4j IF EXISTS.

    		 
    /neo4j-enterprise-5.x/bin/neo4j-admin database restore <databasename> --from-path=/path/to/migration-backups/<databasename>

  4. Migrate each of your restored databases:

    /neo4j-enterprise-5.x/bin/neo4j-admin database migrate <databasename>

  5. Recreate each of your migrated databases:

    CREATE DATABASE <databasename>

  6. (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:

    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'"

  7. (Optional) If you have kept your v4.4 cluster running while setting up the new one, you can stop it now.

  8. Remove the old installation.

Community Edition

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

    /neo4j-community-5.x/bin/neo4j-admin database load --from=/path/to/migration-backups

  2. With the backups in-place, initiate the data migration:

    /neo4j-community-5.x/bin/neo4j-admin database migrate "*"

  3. (Optional) Set the initial password:

    If this step is skipped, the new Neo4j database will have the default password neo4j.

    		 
    /neo4j-community-5.x/bin/neo4j-admin dbms set-initial-password <password>

  4. Start the Neo4j DBMS:

    /neo4j-community-5.x/bin/neo4j start

  5. Remove the old installation.