Migrate a standalone server (Package manager)

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

It is recommended to read the following pages before continuing:

The following example steps assume that the v4.4 Neo4j DBMS is running as systemd service. They use the RPM package manager and Yum as a front end. However, the steps for another package and service manager will be very similar.

For more information on how to configure the Neo4j Yum repository, see Operations Manual → Deploy Neo4j using the Neo4j RPM package. For more information about the supported package and service managers, see Operations Manual → Linux installation.

The Neo4j bin directory must be on a user PATH (default for the RPM package).

Prepare the v4.4 standalone server for migration

Prepare the v4.4 standalone for migration by recreating the indexes and the index-backed constraints to match the new index types.

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.

Stop Neo4j DBMS

Stop Neo4j DBMS v4.4:

sudo systemctl stop neo4j

It is important to verify that the database shutdown process has finished successfully and that the database is cleanly shut down. You can check the neo4j.log using journalctl -e -u neo4j.

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. Update the Neo4j DBMS:

    sudo yum update neo4j

    The RPM package installs the binaries to /usr/share/neo4j, config to /etc/neo4j, and database stores to /var/lib/neo4j. This means that during a package update, only the binaries in /usr/share/neo4j are changed, and users do not need to copy config and database stores from the old installation to the new one.

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

    		 
    neo4j-admin server migrate-configuration

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

  1. Migrate all databases:

    neo4j-admin database migrate "*"

  2. Start the Neo4j DBMS:

    (sudo) systemctl start neo4j

Monitor the logs

The neo4j.log file contains information on how many steps the migration will involve and how far it has progressed. You can monitor this log using journalctl -e -u neo4j.