How to prepare for migrating from Aura 3 to Aura 4 ?

Our long existing customers who started the journey with the Aura service for some time would have their AuraDB Instance running on Aura 3. Since then we have launched Aura 4 (and by that we mean the latest minor version of Aura 4.x) and as we plan to retire Aura 3 there is a need to plan for a migration and upgrade of your application and AuraDB Instance.

AuraDB Free tier customers are on AuraDB 4 and have no need to take any actions. 

Check the version you are running to verify your instance needs migration

You can verify the version using one of the following methods 

• Logon to the aura console https://console.neo4j.io - If the version is displayed this is Aura 4 otherwise it is Aura 3.5:
  
• Running some cypher in the Desktop/Browser: see https://neo4j.com/developer/kb/cypher-to-determine-version-and-edition-of-neo4j/
• Launching cypher-shell and reading it from the prompt:
  From a shell run this

export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD='some_secure_password_for_my_database'
export NEO4J_URI='neo4j+s://zzzzzzz.databases.neo4j.io'
$ cypher-shell -a "$NEO4J_URI"
Connected to Neo4j 4.1.0 at neo4j+s://zzzzzz.databases.neo4j.io:7687 as user neo4j.
Type :help for a list of available commands or :exit to exit the shell.
Note that Cypher queries must end with a semicolon.
neo4j@neo4j>

What are the important elements that have changed and that you need to take into consideration ?

1. Planning: you will need to allocate some time for the upgrade of your application and dedicate some time to test and validate that all works well with Aura 4 before switching versions.
2. Preparation: you should take the time to review the main changes and verify you understand and can carry the modifications. Notably review with great care the release notes for Neo4j 4.0.x, Neo4j 4.1.x , Neo4j 4.2.x , Neo4j 4.3.x as well as Neo4j 4.4.x.
3. Testing : you should take the opportunity to create a second AuraDB Instance running on Aura 4 and run some tests as if it were the production load ahead of making the switch.
4. Validation and switching over

Generic short list of changes 

The following list describe the main considerations and changes that you must take into account to ensure you are successful in your upgrade

• Breaking changes:
  • parameters syntax has changed : old `{variable}` to new `$variable`.
    The new syntax was already supported in Aura 3 but the older syntax is deprecated in Aura 4 and now throws an error.
• Index: Loading a dump / Export will not work optimally with existing pre-existing index and as such you should drop and then create new ones on Aura 4 to get the latest improvements. This in particular is true for fulltext index. 
• Optimisations: Importing a dump will put you on a compatible datastore format but not the latest. To get the latest currently you need to either do this datastore upgrade via a staging step ( do a local upgrade using the Community Edition) or create yourAuraDB Instance form scratch and import only the data.
  • Run neo4j-admin store-info to verify the datastore version
  • See https://neo4j.com/docs/operations-manual/current/tools/neo4j-admin/ 
• Driver versions: In general most drivers that worked with Aura 3 have already a version that is backward compatible. Consider this as perhaps a first step of your upgrade and try using the latest driver against your Aura 3 to ensure you have completed one crucial part of the interaction between your application and Aura.
  • Java 
  • Python driver
  • Java SDN/OGM
  • Javascript
  • GO / GOLANG
  • For community drivers you should take additional time to validate