Upgrade from older versions
This page contains the list of new features and breaking changes of the driver from version 4.4 to 5.x. For a full list of changes, see the Driver → Changelog.
The Neo4j Drivers Migration Assistent simplifies the upgrade process by contextualizing the changelog to your application. It scans your codebase for usage of deprecations and removals, and brings them up to you. The tool doesn’t automatically rewrite your code; it only points at where action is needed, providing in-context information on how each hit should be addressed.
The latest driver version of the 5.x series (5.27) is compatible with Neo4j server both 4.4 and 5.x, so you can upgrade the driver before you upgrade the server. At the same time, the driver version 4.4 is forward compatible with Neo4j server 5.x, so you could also upgrade the server before the driver; however, given that it’s easier to roll back an application upgrade than a server upgrade, it’s recommended to start with the driver.
When upgrading the Neo4j server to a newer version, the Cypher queries in your application may also need updating.
The Drivers Migration Assistent doesn’t cover Cypher changes. See Cypher → Deprecations, additions, and compatibility. |
Recommended steps
Using the migration assistant, the recommended upgrade steps are:
-
Set up the environment for the assistant to work in. Download the Drivers Migration Assistant zip, extract it, and locate yourself in its directory. Then, assuming
python3
andpip3
are already installed,python3 -m venv virtualenvs/neo4j-migration source virtualenvs/neo4j-migration/bin/activate pip3 install -r requirements.txt
-
Run the migration assistant with its default configuration and address all the issues that it surfaces. The
path
argument supports globbing, and can be repeated.python3 main.py -l go /path/*.go /path-recursive/**/*.go
-
Re-run the assistant with the regex parser and check if any more legit issues are raised.
python3 main.py -l go --regex-parser /path/*.go /path-recursive/**/*.go
The regex parser can detect implicit function calls and other hard-to-parse expressions, but is likely to surface more false positives (for more information, see Neo4j Drivers Migration Assistant → Accuracy). You can add any spurious entry to the ignored list, so that the assistant won’t bring them up in future runs.
-
Although the assistant can detect most of the locations where action is needed, a few changelog entries can’t be surfaced in this form, so you should still revise the breaking changes section and audit your codebase for the changes marked with in the table.
-
You are ready to upgrade the driver package to the new version.
Note that your include directives will need to be updated too.go get github.com/neo4j/neo4j-go-driver/v5
New features
Support for Go up to 1.23The driver is compatible with any Go version starting from 1.18 up to 1.23. |
|
Support for user-provided
|
Improved support for genericsFunctions Functions |
Re-authenticationAllows for rotating authentication tokens as well as session-scoped and query-scoped authentication. |
Mutual TLS (mTLS) as second authentication factor (2FA)Allows for configuring client side TLS certificates to authenticate against the server. See Mutual TLS. |
|
Notification filtering APIFiltering allows to receive only a subset of notifications from the server, and to improve performance server-side. |
GQL statuses of queries in the
|
TelemetryThe driver sends anonymous API usage statistics to the server.
Use the driver configuration For more information, see Telemetry API. |
Breaking changes and deprecations
The column Assistant
denotes whether the Neo4j Drivers Migration Assistant can detect issues related to the given changelog entry.
Entries with a cross mark require manual inspection.
Deprecated features are likely to be removed in version 6.
Version | Message | Status | Assistant |
---|---|---|---|
5.0 |
Minimum supported Go version is 1.18. |
Changed |
|
5.0 |
|
Changed |
|
5.0 |
Operations on closed sessions fail with error with |
Changed |
|
5.0 |
|
Changed |
|
5.0 |
A transaction timeout of |
Changed |
|
5.0 |
|
Removed |
|
5.0 |
|
Removed |
|
5.0 |
|
Removed |
|
5.0 |
|
Removed |
|
5.0 |
|
Removed |
|
5.0 |
Some of the previously exported types from |
Removed |
|
5.0 |
|
Removed |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.0 |
|
Deprecated |
|
5.8 |
|
Deprecated |
|
5.8 |
|
Deprecated |
|
5.8 |
|
Deprecated |
|
5.17 |
|
Deprecated |
|
5.17 |
|
Deprecated |
|
5.17 |
|
Deprecated |
|
5.17 |
Types |
Deprecated |
|
5.23 |
Notifications-related objects have been moved from the global namespace |
Deprecated |