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.

Using the migration assistant, the recommended upgrade steps are:

  1. 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 and pip3 are already installed,

    python3 -m venv virtualenvs/neo4j-migration
source virtualenvs/neo4j-migration/bin/activate
pip3 install -r requirements.txt

  2. 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 javascript /path/*.js /path-recursive/**/*.js

  3. Re-run the assistant with the regex parser and check if any more legit issues are raised.

    python3 main.py -l javascript --regex-parser /path/*.js /path-recursive/**/*.js

    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.

  4. 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.

  5. You are ready to upgrade the driver package to the new version. For example, using npm:

    npm update neo4j-driver@5.27

New features

Driver.executeQuery() to run transactions with less knowledge of driver’s internals

The new function is a wrapper for Session.executeRead/Write(), but it abstracts away the result processing part and returns a list of records to the caller directly.

See Query the database.
Explicit resource management to Driver, Session, Transaction objects

Possible to create drivers, sessions, and transactions using the await using keywords and not have to close the resource when done. The resources will be automatically closed when leaving the block that instantiated it.
Type mapping for records from queries

Returned records from queries can be mapped to specific interface definitions, allowing safe access to the record’s properties.

See Type mapping to Result, Session.run, and Transaction.run.
Re-authentication

Allows 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.
BookmarkManager support

Bookmark managers make it easier to achieve causal chaining of sessions.

See Coordinate parallel transactions.
Notification filtering API

Filtering allows to receive only a subset of notifications from the server, and to improve performance server-side.

See Explore the query execution summary → Filter notifications.
GQL statuses of queries in the ResultSummary

The property ResultSummary.gqlStatusObjects contains a sequence of GqlStatusObject, holding information about the execution of the query.

This API is planned to supersede the current notifications API.

See Explore the query execution summary → Notifications.
Telemetry

The driver sends anonymous API usage statistics to the server. Use the driver configuration telemetryDisabled: true to opt out.

See Metrics/Telemetry.

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

ResultSummary.ServerInfo — ResultSummary.server.version has been removed. Use ResultSummary.server.agent, ResultSummary.server.protocolVersion, or call the dbms.components Cypher procedure instead.

Removed

5.0

RxJS was bumped to 7.5.5.
concat was replaced by concatWith, flatMap was replaced by mergeMap.

Changed

5.0

Session — Methods .readTransaction() and .writeTransaction() are deprecated in favor of .executeRead() and .executeWrite(). Through the new methods, the first argument of transaction functions is a ManagedTransaction object. It behaves like a regular Transaction object, except it does not offer the .commit(), .rollback(), .close(), and .closed() methods.

Deprecated

5.0

Session — Method .lastBookmark() is deprecated in favor of .lastBookmarks().

Deprecated

5.0

Node, Relationship — Property .identity (NumberOrInteger) is deprecated in favor of .elementId (String).

Deprecated

5.0

Relationship — Properties .start and .end are deprecated in favor of .startNodeElementId and .endNodeElementId. Old identifiers were NumberOrInteger, wereas new ElementIds are string.

Deprecated

5.0

Driver — The return value of .verifyConnectivity() is deprecated. The method still exists, but returns void. To retrieve the server info, use .getServerInfo().

Deprecated

5.7

Notification — Property .severity is deprecated. Use .rawSeverityLevel for the raw value and .severityLevel for an enumerated value.

Deprecated

5.27

ResultSummary — Property .notifications is deprecated in favor of .gqlStatusObjects. The replacement contains GQL-complaint statuses (GqlStatusObject), which are a superset of the old notifications.

Deprecated