Upgrade to Neo4j 5 within Aura
This tutorial describes how to upgrade an Aura instance running Neo4j version 4 to Neo4j version 5.
New AuraDS and AuraDB Free instances use Neo4j 5 as standard, while all others give the option to choose between Neo4j 4 and 5 during creation. |
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:
-
Check the breaking changes for each driver you use, for example in the Python driver and in the GDS client.
-
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 5.x drivers are backward compatible.
The Update and migration guide contains all information and lists all the breaking changes.
Indexes
In Neo4j 5, BTREE indexes are replaced by RANGE, POINT, and TEXT indexes.
Before migrating a database, in Neo4j 4, you should create a matching RANGE, POINT, or TEXT index for each BTREE index (or index-backed constraint).
You can run SHOW INDEXES
on your Neo4j 4 database to display its indexes.
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
anddistance
orbounding 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
andCONTAINS
andENDS WITH
are used in queries for the property.
After creating the new index, the old index should be dropped.
The following example shows how to create a new RANGE index and drop an existing index_name
index:
CREATE RANGE INDEX range_index_name FOR (n:Label) ON (n.prop1);
DROP INDEX index_name;
The following example instead shows how to create a constraint backed by a RANGE index:
CREATE CONSTRAINT constraint_with_provider FOR (n:Label) REQUIRE (n.prop1) IS UNIQUE OPTIONS {indexProvider: 'range-1.0'}
For more information about creating indexes, see Cypher Manual → Creating indexes.
Cypher updates
Neo4j 5 introduces some changes to the Cypher syntax and error handling.
Cypher syntax
All changes in the Cypher language syntax are detailed in 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.
Here is a short list of the main changes introduced in Neo4j 5:
Deprecated feature | Details |
---|---|
|
Use the
|
|
|
|
Creating a database with unescaped dots in the name has been deprecated, instead escape the database name:
|
Error handling in Cypher
Many semantic errors that Cypher finds are reported as Neo.ClientError.Statement.SyntaxError
even though they are semantic and not syntax errors.
In Neo4j 5, the metadata returned by Cypher queries is improved.
-
The severity of some of the Warning codes is moved to Info:
-
SubqueryVariableShadowingWarning
→SubqueryVariableShadowing
-
NoApplicableIndexWarning
→NoApplicableIndex
-
CartesianProductWarning
→CartesianProduct
-
DynamicPropertyWarning
→DynamicProperty
-
EagerOperatorWarning
→EagerOperator
-
ExhustiveShortestPathWarning
→ExhaustiveShortestPath
-
UnboundedVariableLengthPatternWarning
→UnboundedVariableLengthPattern
-
ExperimentalFeature
→RuntimeExperimental
-
APOC
All APOC procedures and functions available in Aura are listed in the APOC Core library. See the APOC documentation for further details.
Procedures
Some procedures have been replaced by commands:
Procedure | Replacement |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
- |
Refer to the Update 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 5.
The Neo4j BI Connectors available on the Download center are compatible with Neo4j 5.