For a successful migration to AuraDB from an earlier version of neo4j you should consider the changes that have occurred in between versions.

AuraDB is running the latest version available of the neo4j database and this needs to be considered when migrating.

A summary of changes is provided in the changelogs and you need to review with great care :

• Change log for 3.3: https://github.com/neo4j/neo4j/wiki/Neo4j-3.3-changelog 
• Change log for 3.4: https://github.com/neo4j/neo4j/wiki/Neo4j-3.4-changelog
• Change log for 3.5: https://github.com/neo4j/neo4j/wiki/Neo4j-3.5-changelog 
• Change log for 4.0: https://github.com/neo4j/neo4j/wiki/Neo4j-4.0-changelog 
• Change log for 4.1: https://github.com/neo4j/neo4j/wiki/Neo4j-4.1-changelog 
• Change log for 4.2: https://github.com/neo4j/neo4j/wiki/Neo4j-4.2-changelog 
• Change log for 4.3: https://github.com/neo4j/neo4j/wiki/Neo4j-4.3-changelog 

Upgrade path

Currently to successfully load a dump file to AuraDB it needs to be taken from a database version 3.5.x or later.

For full details of upgrade path please see:  

• Upgrade path to 3.5 latest: https://neo4j.com/docs/operations-manual/3.5/upgrade/planning/ 
• For earlier and up to 3.4 : https://neo4j.com/docs/operations-manual/3.4/upgrade/planning/ 
• For earlier and up to 3.2 : https://neo4j.com/docs/operations-manual/3.2/upgrade/planning/ 

Here we assume you can upgrade to the minor versions mentioned in the upgrade path.

The upgrade path relies on the ability to update to the latest revision of that minor version (Major.Minor.Revision). 

Once you have an upgrade path of versions you will need to upgrade your database.

 

Produce a suitable dump file

The first step is to produce a database dump file (use the .dump extension as this is what AuraDB will expect). For this you will need to stop your database.

Note that you should always drop the indexes and in particular drop the full-text indexes to ensure successful and speedier upgrades.

As a validation we recommend that you test the dump file produced is valid with decompressing the file using `zstd` (apt-get install zstd or https://github.com/facebook/zstd) and check the output has content. 

 

Upgrade the dump file as per the upgrade path - Use the Desktop for standalone installations

Using the Desktop it is easy to download and install locally a particular version of neo4j Enterprise and proceed to upgrades with all the administrative tools.

 
You may need to iterate these steps depending on your upgrade path.

Here the target version is 3.5.28 (adjust as necessary if you need to do 3.3.x-latest -> 3.4.x-latest first)    

1. Download Neo4j latest Desktop https://neo4j.com/download/
2. Desktop GUI - Create a local database version 3.5.28. (Add->Local DBMS + Select version 3.5.28)
3. Desktop GUI - Start it (to check all is successful) and then stop it
4. Based on your datastore size you will need to setup appropriate memory settings for your instance (simplest is copy the settings form your existing neo4j.conf ) to be able to load the database.
   This is done via Button "..." -> Settings and you should edit the few basics ( dbms.memory.heap.initial_size, dbms.memory.heap.max_size, dbms.memory.pagecache.size)
   Note: a rule of thumb is to increase these 3 values proportionally and always use a 2^n value.
5. Open a terminal (via "..." -> Terminal button).Use the command to import your existing Dump file (prior to do that please store a copy safely somewhere else ) run
   neo4j-admin load --from=<archive-path> --database=<database> --force
   See this: https://neo4j.com/docs/operations-manual/current/tools/dump-load/
   Note: The default database name is neo4j.db
6. Start the database . It will detect the store version and upgrade it and once started check via Browser that the content is fine.
7. Stop the database
8. We can now re-export the database. Open a terminal (step #5). Use the command to create a Dump file from your datastore ( use filename with a .dump extension). Run
   neo4j-admin dump --database=<database> --to=<destination-path>See this: https://neo4j.com/docs/operations-manual/current/tools/dump-load/

 

Upload your dump file to AuraDB

See this either of these articles:

• https://aura.support.neo4j.com/hc/en-us/articles/360051366094-Running-push-to-cloud-to-load-a-database-dump-file-to-Aura
• https://aura.support.neo4j.com/hc/en-us/articles/360048499853-Upgrading-Your-Existing-Aura-3-5-Database-to-Aura-4 

 

Rebuild your index and constraints

Once you have loaded your database to AuraDB you should rebuild your indexes and constraints to ensure full data integrity and optimal performance. Full text-index were dropped before importing to Aura and will need to be rebuilt.

A more systematic approach is possible as per the steps described in this KB

The nature of the task is essentially as described here:

1.  List your index and constraints and take note of what they reference relative to your graph model:
   in the Browser use the procedures: CALL db.indexes() and CALL db.constraints() or with the Cypher commands: SHOW INDEXES and SHOW CONSTRAINTS
2. Drop all your indexes and constraints DROP INDEX and DROP CONSTRAINT
3. In a separate transaction (from the DROP INDEX command) create 1 by one your indexes and constraints. 

 

Drivers

You should update your application driver to the versions supported by AuraDB.

One important change is that AuraDB requires to make use of the new URI scheme (see details here: https://aura.support.neo4j.com/hc/en-us/articles/360049426414-Neo4j-4-0-drivers-and-new-URI-connection-schemes).

Note that moving from on-premise to AuraDB also means that some drivers have additional requirements and if you were using community drivers, please review this: https://aura.support.neo4j.com/hc/en-us/articles/360056844774-Using-Community-Drivers-Clients-with-Neo4j-Aura.

 

Test your application and Cypher queries

Before you move to production you should allow some testing period to validate all the changes.

In particular this means you should also be reviewing the cypher execution still complies with any of the syntax changes that occurred between the two versions and consider refactoring queries to benefit form any available performance improvements.