Migrate a version 4 instance to the latest version

This tutorial describes how to migrate an Aura instance running Neo4j 4 to the latest version of Neo4j.

  • New instances are created with the latest version of Neo4j.

  • The Migration Readiness Report in the Aura console helps Neo4j Aura 4 users prepare for migration.

Prepare for the upgrade

Drivers

Neo4j’s official drivers have some significant and breaking changes between versions you need to be aware of. For a smooth migration:

  1. Check the breaking changes for each driver you use, for example in the Python driver and in the GDS client.

  2. Make sure you switch to the latest version of the driver in line with the version of the Neo4j database. This can be done before upgrading the version of Neo4j that you are using with Aura, as Neo4j latest version drivers are backward compatible.

The Upgrade and migration guide contains all information and lists all the breaking changes.

Indexes

In Neo4j 5, BTREE indexes were replaced by RANGE, POINT, and TEXT indexes. These indexes are not automatically created during migration, so you must manually create an equivalent index for each BTREE index in Neo4j 4.

The SHOW INDEXES command lists all database indexes.

If your database is running Neo4j 4.4 or later, you can create these new index types before migrating. Read more in the Cypher Manual > Future Indexes.

RANGE indexes can replace most BTREE indexes.

TEXT indexes are more appropriate for queries evaluating STRING predicates involving the CONTAINS or ENDS WITH operators. For more information, see the Cypher Manual → Create text indexes.

POINT indexes should be used for queries evaluating POINT values. For more information, see the Cypher Manual → Create point indexes.

After creating the new index, the old index should be dropped.

Create a range index and drop an existing BTREE index
CREATE RANGE INDEX range_index_name FOR (n:Label) ON (n.prop1);
DROP INDEX index_name;

Propety uniqueness and key constraints are backed by indexes. For more information, see the Cypher Manual → Constraints and backing indexes.

For information about indexes and query performance, see the link: Cypher Manual → The impact of indexes on query performance.

Cypher updates

All changes to Cypher, including feature additions, deprecations, and removals, are introduced in Neo4j versions. For more information, see the Cypher Manual → Removals, deprecations, additions and extensions.

Thoroughly review this section in the version you are moving to and make the necessary changes in your code.

APOC

Aura contains most but not all functions and procedures contained in the APOC Core library. All APOC procedures and functions available in Aura are listed in the APOC Core library.

Procedures

Some procedures have been replaced by commands:

Procedure Replacement

db.indexes

SHOW INDEXES command

db.indexDetails

SHOW INDEXES YIELD * command

db.schemaStatements

SHOW INDEXES YIELD * command and SHOW CONSTRAINTS YIELD * command

db.constraints

SHOW CONSTRAINTS command

db.createIndex

CREATE INDEX command

db.createUniquePropertyConstraint

CREATE CONSTRAINT …​ IS UNIQUE command

db.index.fulltext.createNodeIndex

CREATE FULLTEXT INDEX command

db.index.fulltext.createRelationshipIndex

CREATE FULLTEXT INDEX command

db.index.fulltext.drop

DROP INDEX command

dbms.procedures

SHOW PROCEDURES command

dbms.functions

SHOW FUNCTIONS command

dbms.listTransactions

SHOW TRANSACTIONS command

dbms.killTransaction

TERMINATE TRANSACTIONS command

dbms.killTransactions

TERMINATE TRANSACTIONS command

dbms.listQueries

SHOW TRANSACTIONS command

dbms.killQuery

TERMINATE TRANSACTIONS command

dbms.killQueries

TERMINATE TRANSACTIONS command

dbms.scheduler.profile

-

Refer to the Upgrade and migration guide for a full list of removals and deprecations.

Neo4j Connectors

If you are using a Neo4j Connector for Apache Spark or Apache Kafka, make sure its version is compatible with Neo4j latest version.

The Neo4j BI Connectors available on the Deployment center are compatible with Neo4j latest version.

Perform the upgrade

Once you have prepared your Neo4j 4 Aura instance, you are ready to migrate the instance to a new or existing Neo4j latest version instance.

Clone

If you have an existing Neo4j latest version instance, you can use the Clone To Existing instance action on your Neo4j 4 AuraDB instance.

If you do not have an existing Neo4j latest version instance, you can use the Clone To New instance action on your Neo4j 4 AuraDB instance.

Export and import

Alternatively, you can export a snapshot dump file from your Neo4j 4 AuraDB instance, create a new Neo4j latest version instance manually, and then import the dump file into your new Neo4j latest version instance.

Recreate users and roles in Neo4j Aura

When migrating to a new Aura instance, users and passwords, custom roles and privileges are not copied as part of cloning or dump/restore. To ensure they remain the same, recreate them in the target instance.

Make sure you export the output of all of the Cypher queries detailed in this section, and run every query in the target instance.

Prerequisites

  • Connect to the source database to run the Cypher queries.

  • Run queries against the system database - to switch to the system database, use the :use system command

  • The output of the Cypher queries need to be executed on the target instance.

Export users

The first step is to export the scripts for user creation. The output will default all user passwords to newpassword and the users are required to change their password on initial log-in.

SHOW USERS yield user where user<>'neo4j' return 'CREATE USER '+ user +' SET PASSWORD \'newpassword\' CHANGE REQUIRED;' as output;

Sample output is as follows:

Show users sample output
Figure 1. Export users

Export the output as CSV using Download CSV. Copy the scripts from CSV (exclude the word OUTPUT because it’s a header) and execute them on the cloned instance. You can verify the users are created successfully using the command:

SHOW USERS;

Export roles

The next step is to create roles. This script will generate Cypher to create roles if they do not exist already.

SHOW ROLES yield role return 'CREATE ROLE ' + role + ' IF NOT EXISTS;' as output;

Sample output is as follows:

Show roles
Figure 2. Export roles

You can verify the roles created using the command:

SHOW ROLES;

Assign privileges

Privileges control access rights to graph elements using a combined allowlist/denylist mechanism. The user can access the resource if their roles have a GRANT (allowlist) and do not have a DENY (denylist) relevant to that resource.

SHOW PRIVILEGES AS COMMANDS;

This returns the privileges as the commands that are granted or denied. Execute these commands directly on the cloned Aura instance. If you are getting errors in the syntax, use a semicolon ; at the end of every statement.

Sample output is as follows:

Show privileges as commands
Figure 3. Show privileges as commands

Generate user role mapping Cypher

When creating users in the first step, by default all users got the PUBLIC role which provides access to the default database and allows the execution of all procedures and user-defined functions. Therefore the following script excludes the PUBLIC role and roles with no users mapped.

SHOW ROLES WITH USERS yield member,role where role<>"PUBLIC" and member is not null RETURN 'GRANT ROLE ' + role + ' TO USER ' + member + '' AS OUTPUT;

This generated Cypher scripts to map users to roles. Copy and execute these on the cloned instance to create user role mappings.

Sample output is as follows:

Generate roles
Figure 4. Generate user role mapping Cypher

You can verify the mapping by using the command:

SHOW ROLES WITH USERS;