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.

Prerequisites

  • Sign into your source database because you will run the Cypher queries on it.

  • Ensure you are using the system database with the :use system command

  • The output of the Cypher queries below can be played back on the cloned 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 (but do not take the word output) 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 for roles that need to be created 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 will be able to 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. You can now execute these commands directly to the cloned Aura instance. Make sure to use a semicolon ; at the end of every statement if you are getting errors in the syntax.

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 script below will exclude 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 will generate 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;

Make sure you export the output of all of the above Cypher queries and run every query to avoid any mismatch in the roles and mappings.