Breaking changes

This section describes the breaking changes between Neo4j 1.7 drivers and 4.x drivers.

Configuration

  • The drivers' default configuration for encrypted is now false, meaning that driver will attempt only plain text connections by default. Connections to encrypted services (such as Neo4j Aura) must be set to encrypted.

  • When encryption is explicitly enabled, the default is to trust the CAs trusted by the operating system. This means that, by default, encrypted connections to servers holding self-signed certificates fail on certificate verification.

  • Hostname verification is turned on by default when encryption is turned on.

For more information, see The Neo4j Drivers Manual 4.0 → Configuration.

Removal of the version suffix

v1 is removed from drivers’ package name. For example, in the Java driver, all public APIs are in the package org.neo4j.driver instead of the old org.neo4j.driver.v1.

Connection URI scheme

Neo4j 4.0 exposes a routing interface for all deployment topologies, allowing neo4j:// URIs to be used for all deployments.

Neo4j 3.x standalone instances do not expose a routing interface.

  • The neo4j:// scheme replaces bolt+routing:// and can be used for both clustered and single-instance configurations. This is a rename only, and neo4j:// URIs can still be used to communicate with Neo4j 3.x clusters.

  • The bolt:// scheme is used for direct connection to a particular Neo4j server. However, this scheme is no longer required for standalone machines.

  • The bolt:// scheme is mainly useful when not targeting an entire service, but rather a specific machine, such as a certain server in a Causal Cluster or the one server in a single-instance environment.

  • The recommended Driver Connection URI scheme is as follows:

    Table 1. Recommended Driver Connection URI scheme.

    4.0 drivers

    1.7 drivers

    4.0 Neo4j

    Single instance

    neo4j

    bolt

    Cluster core members

    neo4j

    neo4j (bolt+routing)

    Cluster read replicas

    neo4j

    bolt

    3.5 Neo4j

    Single instance

    bolt

    bolt

    Cluster core members

    neo4j

    neo4j (bolt+routing)

    Cluster read replicas

    bolt

    bolt

Changes in drivers' methods

  • For drivers where synchronous and asynchronous methods are both implemented, asynchronous methods are extracted out and put in AsyncSession, whereas synchronous methods remain in Session. This change ensures that blocking and non-blocking APIs can never be mixed together.

  • Driver#session method uses a session configuration object or option builder, rather than method arguments.

  • Bookmark has changed from a string, and/or a list of strings, to a Bookmark object.

  • For synchronous Transaction API, Transaction#success and Transaction#failure are removed.

  • The success/close pattern for Transaction objects is now obsolete and is fully superseded by commit and rollback methods. However, unlike Transaction#success, which only marks the transaction as successful and then waits for Transaction#close to perform the actual commit, Transaction#commit commits the transaction immediately.

    A transaction in 4.0 can only be committed or rolled back once. If a transaction is not committed explicitly using Transaction#commit, Transaction#close will roll back the transaction.

  • Statement is renamed to Query. StatementResult is renamed to Result. Similarly, StatementResultCursor is renamed to ResultCursor.

  • A result can only be consumed once.

  • A result is consumed if either the query result has been discarded by invoking Result#consume, and/or the outer scope where the result is created, such as a transaction or a session, has been closed. Attempts to access consumed results are responded with a ResultConsumedException.

  • The experimental StatementRunner.typeSystem() is moved to Driver.defaultTypeSystem().

  • LoadBalancingStrategy is removed from Config class and the drivers always default to LeastConnectedStrategy.

For more information on breaking changes for the specific drivers, see their respective sections: