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 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.
See Cypher → Deprecations, additions, and compatibility.

New features

Run transactions with less knowledge of driver’s internals

The new method Driver.executableQuery() 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. For more information, see Query the database.

The new method Session.executeWriteWithoutResult() allows for running write queries without result processing.
Packaging changes

The org.neo4j.driver:neo4j-java-driver artifact no longer includes shaded Netty and Project Reactor dependencies and replaces the org.neo4j.driver:neo4j-java-driver-slim introduced in version 4.4.

A new org.neo4j.driver:neo4j-java-driver-all artifact includes shaded Netty and Project Reactor dependencies dependencies and is similar to the original packaging of the org.neo4j.driver:neo4j-java-driver before this update.

The org.neo4j.driver:neo4j-java-driver includes an explicit module declaration for Java Platform Module System (JMPS). The module name remains unchanged.
New reactive sessions

New ReactiveSession (Flow) and ReactiveSession (reactivestreams) implementations.

For more information, see Control results flow with reactive streams.
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.

For more information, see Coordinate parallel transactions, BookmarkManager, and Update to Bookmarks API.
Notification filtering API

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

For more information, see Explore the query execution summary → Filter notifications.
GQL statuses and errors

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.

Interface Neo4jException exposes GQL metadata as well.

For more information, 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 API Telemetry.

Breaking changes and deprecations

Deprecated features are likely to be removed in version 6.

Version Message Status

5.0

Baseline Java version 17.

Changed

5.0

GraphDatabase — Method .routingDriver() has been removed. Use .driver() instead.

Removed

5.0

ServerInfo — Method .version() has been removed. Use .agent(), .protocolVersion(), or call the dbms.components Cypher procedure instead.

Removed

5.0

Session — Method .reset() has been removed without replacement.

Removed

5.0

Neo4jException — Method .neo4jErrorCode() has been removed in favor of .code().

Removed

5.0

Session — Methods .readTransaction() and .writeTransaction() are deprecated in favor of .executeRead() and .executeWrite(). The same holds for their async conterparts .executeReadAsync() and .executeWriteAsync(). The new methods behave similarly, but the argument types are different and the new methods do not support the .commit(), .rollback(), .close(), and .closed() methods.

Deprecated

5.0

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

Deprecated

5.0

Session — Methods .asyncSession() and reactiveSession() are deprecated. Use Session(Class), with Class controlling what type of session you wish for.

Deprecated

5.0

Node, Relationship — Method .id() (long) is deprecated in favor of .elementId() (string).

Deprecated

5.0

Relationship — Methods .startNodeId() and .endNodeId() are deprecated in favor of .startNodeElementId() and .endNodeElementId(). Old identifiers were long, wereas new ElementIds are string.

Deprecated

5.0

Reactive sessions — Interface RxSession is deprecated in favor of ReactiveSession (Flow) and ReactiveSession (reactivestreams).

Deprecated

5.7

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

Deprecated