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 go /path/*.go /path-recursive/**/*.go

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

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

The driver is compatible with any Go version starting from 1.18 up to 1.23.
neo4j.ExecuteQuery() to run transactions with less knowledge of driver’s internals

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

See Query the database.
Support for user-provided Context instances

A long requested feature from the community: the driver now exposes a set of APIs that take user-provided instances of context.Context into account. The entry point is neo4j.NewDriverWithContext().
Improved support for generics

Functions neo4j.GetRecordValue() and neo4j.GetProperty() allow to extract properties and record values of the specified type.

Functions neo4j.ExecuteRead() and neo4j.ExecuteWrite() provide generic variants of SessionWithContext.ExecuteRead/Write().
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

These are GQL-compliant status objects. A new method ResultSummary.GqlStatusObject() is available. It returns a list of GqlStatusObject, containing 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 TelemtryDisabled = true to opt out.

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

ExplicitTransaction — Calling Rollback() or Commit() multiple times is now prohibited and results in a UsageError.

Changed

5.0

Operations on closed sessions fail with error with Operation attempted on a closed session.

Changed

5.0

ResultSummary.ContainUpdates() — In 4.x, the function returned true if any of the summary counters were strictly positive. It now returns true only if at least a deletion or creation of the following entities happened: constraint, index, node, relationship, label, property.

Changed

5.0

A transaction timeout of 0 (which is not the default value anymore) now disables the timeout on the server side. If no timeout is specified, the server uses the server-defined timeout.

Changed

5.0

Driver.Session() has been removed in favor of DriverWithContext.NewSession().

Removed

5.0

Query.Params() has been removed in favor of Query.Parameters().

Removed

5.0

Record.GetByIndex() has been removed. Access the Record.Values struct slice directly instead.

Removed

5.0

ResultSummary.Statement() has been removed in favor of ResultSummary.Query(). The new method returns a Query rather than a Statement object.

Removed

5.0

Session.LastBookmark() is deprecated in favor of Session.LastBookmarks(). The logic is similar, but the new method returns neo4j.Bookmarks instead of string.

Removed

5.0

Some of the previously exported types from neo4j.db are now internal.
For db.AccessMode, db.WriteMode and db.ReadMode, use neo4j.AccessMode, neo4j.AccessModeWrite and neo4j.AccessModeRead.
For db.TxConfig, use neo4j.TransactionConfig.
All others have no replacement: db.TxHandle, db.StreamHandle, db.Command, db.Connection, db.RoutingTable, db.DefaultDatabase, db.DatabaseSelector.

Removed

5.0

ServerInfo.Version has been removed. Use ServerInfo.Agent, ServerInfo.ProtocolVersion, or call the dbms.components Cypher procedure instead.

Removed

5.0

NewDriver() is deprecated in favor of NewDriverWithContext(). The behavior is similar, except that the new function takes a ctx.Context as first argument.

Deprecated

5.0

Session.WriteTransaction() and Session.ReadTransaction() are deprecated in favor of Session.ExecuteWrite() and Session.ExecuteRead(). The logic is the same, but the argument type changed from Transaction to ManagedTransaction, and explicit transaction handling methods (.Commit(), .Rollback(), .Close()) are not available on managed transactions anymore.

Deprecated

5.0

Node.Id and Relationship.Id are deprecated in favor of Node.ElementId and Relationship.ElementId. Old identifiers were Int64, wereas new ElementIds are String.

Deprecated

5.0

neo4j.SingleT() is deprecated in favor of neo4j.SingleTWithContext(). The behavior is similar, except that the new function takes a ctx.Context as first argument.

Deprecated

5.0

neo4j.Collect() is deprecated in favor of neo4j.CollectWithContext(). The behavior is similar, except that the new function takes a ctx.Context as first argument.

Deprecated

5.0

neo4j.CollectT() is deprecated in favor of neo4j.CollectTWithContext(). The behavior is similar, except that the new function takes a ctx.Context as first argument.

Deprecated

5.0

neo4j.Session is deprecated in favor of neo4j.SessionWithContext.

Deprecated

5.0

neo4j.Driver is deprecated in favor of neo4j.DriverWithContext.

Deprecated

5.0

neo4j.Transaction is deprecated in favor of neo4j.ExplicitTransaction.

Deprecated

5.0

neo4j.TransactionWork is deprecated in favor of neo4j.ManagedTransactionWork.

Deprecated

5.0

neo4j.Result is deprecated in favor of neo4j.ResultWithContext.

Deprecated

5.0

Config.RootCAs is deprecated in favor of Config.TlsConfig.

Deprecated

5.8

neo4j.Config is deprecated in favor of config.Config.

Deprecated

5.8

neo4j.ServerAddress is deprecated in favor of config.ServerAddress.

Deprecated

5.8

neo4j.ServerAddressResolver is deprecated in favor of config.ServerAddressResolver.

Deprecated

5.17

neo4j.(LogLevel|ERROR|WARNING|INFO|DEBUG) are deprecated in favor of log.(Level|ERROR|WARNING|INFO|DEBUG).

Deprecated

5.17

neo4j.ConsoleLogger() is deprecated in favor of neo4j.log.ToConsole(). The behavior is similar, except that the new function takes a ctx.Context as first argument.

Deprecated

5.17

neo4j.ConsoleBoltLogger() is deprecated in favor of neo4j.log.BoltToConsole().

Deprecated

5.17

Types neo4j.log.Console and neo4j.log.Void are deprecated and unified into neo4j.log.Logger.
Functions neo4j.ConsoleLogger() and neo4j.Void() are deprecated in favor of neo4j.log.ToConsole() and neo4j.log.ToVoid(), both returning a neo4j.log.Logger object.

Deprecated

5.23

Notifications-related objects have been moved from the global namespace neo4j into neo4j/notifications — neo4j.(NotificationSeverity|Warning|Information|UnknownSeverity|NotificationCategory|Hint|Unrecognized|Unsupported|Performance|Deprecation|Generic|Security|Topology|UnknownCategory) are deprecated in favor of notifications.(NotificationSeverity|Warning|Information|UnknownSeverity|NotificationCategory|Hint|Unrecognized|Unsupported|Performance|Deprecation|Generic|Security|Topology|UnknownCategory).

Deprecated