Search code, repositories, users, issues, pull requests...

This is a refinement release that brings several improvements and dependency updates.

6.0 API documentation

👏 Improvements

feature(observation): Set driver dependency as provided #1708
feat(query-api): Add support for bearer and none tokens #1713

🔧 Build

build(deps): Update dependencies #1709 #1712

`v6.0.1`

The neo4j-java-driver-bom has been updated to not import netty-bom.

If you are using Netty Native Transport, please ensure to either:

Use a compatible Netty Native Transport version with Netty version used by the driver.
Import netty-bom with the desired Netty version (at present, the driver is shipped with Netty 4.2+)

6.0 API documentation

👏 Improvements

feat(bom): delete netty-bom from neo4j-java-driver-bom #1707

`v6.0.0`

This release brings news features, general improvements and dependency updates.

The sections below describe the main updates in this release and the full changelog is listed in the end.

Java Driver Manual

6.0 API documentation

Neo4j Vector

Neo4j Vector is a new data type introduced in Neo4j server (2025.10, Enterprise Edition).

The driver's type system has been extended to support it.

A new Vector interface represents Neo4j Vector. At present, it has 6 subtypes:

Int8Vector - INTEGER8 vector that has Java byte elements and can be converted to byte[] array
Int16Vector - INTEGER16 vector that has Java short elements and can be converted to short[] array
Int32Vector - INTEGER32 vector that has Java int elements and can be converted to int[] array
Int64Vector - INTEGER vector that has Java long elements and can be converted to long[] array
Float32Vector - FLOAT16 vector that has Java float elements and can be converted to float[] array
Float64Vector - FLOAT vector that has Java double elements and can be converted to double[] array

Similarly to the IsoDuration, new Value instance containing Vector can be created using one of the provided Values#vector(...) factory methods. The Type of such Value is equal to TypeSystem#VECTOR().

Usage example:

var value = Values.vector(new float[] {0.0f});
var result = driver.executableQuery("CREATE (:VectorTest {vector: $vector})")
        .withParameters(Map.of("vector", value))
        .execute();

Since Vector is a sealed interface, it works well with Pattern Matching for switch:

switch (value.asVector()) {
    case Int8Vector int8Vector -> {
        var arr = int8Vector.toArray();
    }
    case Int16Vector int16Vector -> {
        var arr = int16Vector.toArray();
    }
    case Int32Vector int32Vector -> {
        var arr = int32Vector.toArray();
    }
    case Int64Vector int64Vector -> {
        var arr = int64Vector.toArray();
    }
    case Float32Vector float32Vector -> {
        var arr = float32Vector.toArray();
    }
    case Float64Vector float64Vector -> {
        var arr = float64Vector.toArray();
    }
}

Alongside Value#asVector(), it is also possible to map Value to Vector using the Value#as(Class<T>) method. This is especially useful when Vector subtype is well-known:

var vector = value.as(Float32Vector.class);

It is also possible to map to array directly:

var arr = value.as(float[].class);

When using Object Mapping, it is possible to define record components both as Vector and arrays with Vector annotation:

record DomainRecord(
        Float32Vector float32Vector, 
        @&#8203;Vector float floatArr) {}
var domainRecord = value.as(DomainRecord.class);

Unsupported Type

The Neo4j Vector is a good example of a new type being introduced to the system. It is possible that at some point the driver version connecting to the server might not support a new future type because it requires a newer protocol version to support it.

A new UnsupportedType object has been introduced to identify such types and provide some information about them, like:

name
minimum protocol version
an optional message

The Type of a Value with UnsupportedType is equal to TypeSystem#UNSUPPORTED().

Usage example:

var unsupportedType = value.asUnsupportedType();
System.out.println(unsupportedType.name());
System.out.println(unsupportedType.minProtocolVersion());
unsupportedType.message().ifPresent(System.out::println);

Sending the UnsupportedType back to the server is not supported.

Bill of Materials (BOM)

A new Maven artifact neo4j-java-driver-bom represents driver's Bill of Materials (BOM).

It is especially useful when additional driver dependencies are used.

Usage example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

The driver BOM also imports netty-bom to ensure compatible versions, especially when Netty Native Transport is used.

Should it be necessary, users can override netty-bom version by importing it before the driver BOM:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.netty</groupId>
            <artifactId>netty-bom</artifactId>
            <version>${netty-bom.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Query API

NOTE: This feature is in preview.

Neo4j Query API is an HTTP API for executing Cypher statements.

The driver supports connecting to this API over HTTP.

The Query API support is enabled by:

including an extra dependency
using https or http URI scheme

Example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
    <dependency>
        <groupId>org.neo4j.bolt</groupId>
        <artifactId>neo4j-bolt-connection-query-api</artifactId>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <!--> BOM ensures the versions are compatible <-->
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

Driver creation example:

var driver = GraphDatabase.driver("https://query.api.local", authToken);

The are some limitations with this integration at the moment. The main unsuported items are listed below:

Home database resolution.
Records streaming.
- All records are loaded ahead of time to client-side memory. If you deal with large datasets, this integration might need more memory.
Neo4j Vector.
Unsupported Type.
Transaction metadata.
Notification preferences.
ResultSummary#resultAvailableAfter(TimeUnit).
ResultSummary#resultConsumedAfter(TimeUnit).
ResultSummary#queryType().
ResultSummary#plan().
ResultSummary#profile().

Since home database resolution is not supported, the database name MUST be set explicitly using the driver API. Alternatively, it is possible to append the default database name to the URI, it will be used when no database name is set explicitly.

Example: https://query.api.local?defaultDatabase=neo4j

Reducing the number of dependencies

When the driver is used with Query API only, it is possible to exclude some dependencies to reduce the overall amount:

<dependency>
    <groupId>org.neo4j.driver</groupId>
    <artifactId>neo4j-java-driver</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.neo4j.bolt</groupId>
            <artifactId>neo4j-bolt-connection-netty</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Specifically, this removes the following dependencies:

org.neo4j.bolt:neo4j-bolt-connection-netty
- io.netty:netty-handler
  - io.netty:netty-common
  - io.netty:netty-resolver
  - io.netty:netty-buffer
  - io.netty:netty-transport
  - io.netty:netty-transport-native-unix-common
  - io.netty:netty-codec-base
- io.netty:netty-tcnative-classes

Unix Domain Socket

bolt+unix URI scheme allows connecting to Neo4j server over Unix Domain Socket.

Example:

try (var driver = GraphDatabase.driver("bolt+unix:///var/run/neo4j.sock")) {
    var result = driver.executableQuery("SHOW DATABASES")
            .withConfig(QueryConfig.builder().withDatabase("system").build())
            .execute();
    result.records().forEach(System.out::println);
}

While the driver does not impose any special limitations on such connections, the server has a dedicated purpose for them - administration. Therefore, it limits interations to system database only. See the server configuration settings.

Netty Native Transport

Using Netty Native Transport may bring better performance and less garbage collection as mentioned in the Netty documentation.

In addition, TFO is only supported with Netty Native Transport.

The native transport support is limited to the following URI schemes:

neo4j
bolt

Only the following Maven artifacts are supported:

netty-transport-native-io_uring (Netty 4.2+ only)
netty-transport-native-epoll
netty-transport-native-kqueue

The driver automatically uses Netty Native Transport when it is added to runtime.

Example (Maven):

<dependencies>
    <dependency>
        <groupId>org.neo4j.driver</groupId>
        <artifactId>neo4j-java-driver</artifactId>
    </dependency>
    <!--> MUST be added manually for a given system <-->
    <dependency>
        <groupId>io.netty</groupId>
        <artifactId>netty-transport-native-io_uring</artifactId>
        <classifier>linux-x86_64</classifier>
        <scope>runtime</scope>
    </dependency>
</dependencies>

<dependencyManagement>
    <dependencies>
        <!-- Ensures that the dependency versions are compatible -->
        <dependency>
            <groupId>org.neo4j.driver</groupId>
            <artifactId>neo4j-java-driver-bom</artifactId>
            <type>pom</type>
            <scope>import</scope>
            <version>6.0.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

TCP Fast Open (TFO)

NOTE: This feature is experimental.

A working TCP Fast Open setup enables the driver to start one of the following during TCP handshake by sending early data:

Bolt Handshake (for connections not needing encryption)
TLS Handshake (for connections needing encryption)

The following conditions MUST be met for it to work as expected:

Netty Native Transport must be used.
The system the driver is running on MUST:
- Support TFO.
- Have it enabled.
The driver configuration option MUST be enabled.
The endpoint the driver connects to MUST:
- Support TFO.
- Have it enabled both in the system and the Neo4j server.

The driver configuration example:

var config = Config.builder()
        .withTryTcpFastOpen(true)
        .build();

Logging

The driver now uses Java System.Logger by default.

The Logging abstraction has been deprecated for future removal.

Since Java System.Logger uses Java Util Logging (JUL) by default, logging can be adjusted by modifying $JAVA_HOME/conf/loggig.properties file.

There are 2 main root loggers that the driver uses:

org.neo4j.driver - Driver-level logging.
org.neo4j.bolt.connection - Bolt-level logging.

For instance, to see driver logging in console:

Make sure java.util.logging.ConsoleHandler.level is set to the desired logging level.
Add facility-specific properties with desired logging levels for the root loggers.

Example:

java.util.logging.ConsoleHandler.level = FINE

org.neo4j.driver.level = FINE
org.neo4j.bolt.connection.level = FINE

Both System.Logger and JUL can be bridged to other logging solutions should this be needed.

Observability

NOTE: This feature is in preview.

Observability of the driver has been improved in this release.

A new ObservationProvider type provides an integration point for driver observability. There are 2 new driver modules that implement it:

neo4j-java-driver-observation-metrics
neo4j-java-driver-observation-micrometer

The former contains the experimental metrics that the driver used to have previously. They have been moved to this new module.

The latter implements integration with Mictomer Observation API. Micrometer is able to create both metrics and traces providing that the relevant handlers are registered.

See #1682 for more details.

Acquisition timeout

The handling of ConfigBuilder#withConnectionAcquisitionTimeout(long, TimeUnit) has been changed to apply to the whole connection acquisition process. Please see the documentation for more details.

Changelog

Please see the full changelog below.

⭐ New Features

feat(tfo): add experimental support for TFO #1696
feat(unix): add support for bolt+unix #1700
feat(unsupportedType): add support for Bolt Unsupported Type #1691
feat(observability): add Observation SPI #1682
feat(vector): Introduce support for Neo4j Vector #1663
feature(bom): introduce BOM and update to Bolt Connection 4.0.0 #1653
feat(logging): add support for System.Logger and deprecate Logging #1648

👏 Improvements

feat(bom): Add netty-bom to neo4j-java-driver-bom #1706
feat(vector): Make Neo4j Vector GA #1704
feat(vector): add Value#asVector() #1701
feat(tfo): update config naming #1699
test: fix ReactiveResultRecordPublisherVerificationIT #1695
feat(vector): update naming #1692
fix(acquisition): avoid infinite connection timeout if there is a limit #1689
feat(native): add support for Netty native transports #1690
docs(retries): add a note about implicit transaction #1687
feat(acquisition): apply acquisition timeout to all steps #1685
feat(observability): allow setting null provider #1686
feat(observability): add Javadoc #1684
fix(object-mapping): try making record components accessible #1681
docs(retry): mention ExecutableQuery in withMaxTransactionRetyTime #1679
feat(gql-status-object): add legacy notification fields #1677
feat(gql-status-object): Introduce GqlNotification #1667
feat(object-mapping): support mapping types with restricted access #1668
feat(gql-status-object): make GQL Status Object GA #1669
feat(gql-error): add GQLSTATUS finders #1671
feat(gql-error): make GQL Error GA #1673
fix(retry): make RetryLogic executor threads daemon #1661
perf(value): optimise value handling for Bolt Connection #1657
refactor: Fix typo in ErrorMapper.mapAndThrow method #1643
feat: delete deprecated RxSession #1644
feat(bookmarks): delete deprecated multi value support in Bookmark #1646
feat: delete deprecated transaction functions #1647
feat(session): delete deprecated session methods #1649
feat(config): delete deprecated TrustStrategy.certFile() #1650
feat(notification): delete deprecated Notification#severity() #1651
build: build on Java 21 #1645

🔧 Dependency Management

build(deps): update dependencies #1705
build(deps): update dependencies #1694
build(deps): update dependencies #1683
build(deps): update dependencies #1680
build(deps): update Bolt Connection 4.1.0 #1654
build(deps): Update neo4j-bolt-connection to 3.0.0 #1642
build(deps): update neo4j-bolt-connection to 6.0.1 #1664
build(deps): update dependencies #1674

`v5.28.10`

This in an LTS release.

It brings general improvements and dependency updates.

👏 Improvements

docs(retries): add a note about implicit transaction #1688
test: fix ReactiveResultRecordPublisherVerificationIT #1703

🔧 Dependency Management

build(deps): update dependencies #1702

`v5.28.9`

This in an LTS release.

It brings general improvement and dependency update.

👏 Improvements

feat(gql-status-object): add legacy notification fields #1676

🔧 Dependency Management

build(deps): udpate dependencies #1678

`v5.28.8`

This in an LTS release.

It brings general improvements and dependency updates.

👏 Improvements

feat(gql-status-object): Introduce GqlNotification #1641
feat(object-mapping): support mapping types with restricted access #1670
feat(gql-error): add GQLSTATUS finders #1672

🔧 Dependency Management

build(deps): update dependencies #1675

`v5.28.7`

This in an LTS release.

It brings general improvements and dependency updates.

👏 Improvements

fix(retry): make RetryLogic executor threads daemon #1660

🔧 Dependency Management

build(deps): update dependencies #1665

`v5.28.6`

This in an LTS release.

It brings general improvements and dependency updates.

👏 Improvements

perf(value): optimise value handling for Bolt Connection #1658
refactor: Fix typo in ErrorMapper.mapAndThrow method #1643

🔧 Dependency Management

build(deps): update dependencies #1659
build(deps): update dependencies #1656
build(deps): Update neo4j-bolt-connection to 3.0.0 #1642

`v5.28.5`

This in an LTS release.

A new preview feature has been introduced in this release, please read about it in the following discussion.

⭐ New Features

feat: Introduce Value and Record mapping to custom object types #1633
feat(object-mapping): Add support for mapping list value to array #1637
feat(object-mapping): Add support for mapping java.lang.Record to value #1638

👏 Improvements

docs: Update Driver#close() and Driver#closeAsync() documentation #1634
fix: Ensure reactive transaction subsequent runs work during streaming #1636

🔧 Dependency Management

build(deps): Update dependencies #1639

`v5.28.4`

This in an LTS release.

It brings general improvements and dependency updates.

👏 Improvements

perf: Optimise Bolt values unpacking #1629
Support neo4j-bolt-connection testing #1628

🔧 Dependency Management

build: Update dependencies #1630

`v5.28.3`

This in an LTS release.

It brings dependency updates.

👏 Improvements

Update retry delay multiplier in ExponentialBackoffRetryLogic #1622
fix: Make driver more resilient agains already existing attribute keys for Netty channels. #1625
Use neo4j-bolt-connection #1623

🔧 Dependency Management

Update dependencies #1627

`v5.28.2`

This in an LTS release.

It brings dependency updates.

✅ Testkit

TestKit: skip one of the newly added summary tests #1617

🔧 Dependency Management

Update dependencies #1620 #1618

`v5.28.1`

This in an LTS release.

It fixes a bug with database resolution when using ExecutableQuery with neo4j scheme over Bolt 5.8 or higher.

👏 Improvements

Ensure database name on pipelined begin is handled appropriately #1615

`v5.28.0`

This in an LTS release.

A new feature in this release is home database resolution cache. Its objective is to reduce the amount of Bolt exchange roundtrips for home database resolution when Bolt protocol 5.8 or higher is used. It is not exposed in the public API and is meant to be an optimisation.

⭐ New Features

Introduce home database resolution cache #1600

👏 Improvements

Improve transaction failure handling #1598
Update ExponentialBackoffRetryLogic #1603
Fix thread safety in Neo4jBookmarkManager #1604
Update Neo4jException.gqlCause #1608
Add support for Bolt Protocol Handshake Manifest v1 #1605
Internal updates #1590 #1596 #1609 #1610 #1611 #1612 #1613

🔧 Dependency Management

Update dependencies #1614

`v5.27.0`

This release moves the mTLS support to GA status and also brings general improvements and dependency updates.

5.27 API documentation

👏 Improvements

Move mTLS support to GA status #1587
Update handling of cancellation state in reactive result #1583
Update result handlers by refactoring the implementation #1585
Notify handler of all errors in RoutedBoltConnection #1588
Ensure BoltConnection does not send signals after summaries are finished #1592

🔧 Dependency Management

Update dependencies #1584 #1593

`v5.26.3`

This is a patch release that includes improvements in routing handling.

👏 Improvements

Update RoutedBoltConnectionProvider #1582

`v5.26.2`

This is a patch release that includes general improvements and dependency updates.

👏 Improvements

Allow subsequent errors in BoltConnectionWithAuthTokenManager #1579
Update RxResultCursorImpl #1580

🔧 Dependency Management

Update dependencies #1581

`v5.26.1`

This is a patch release that includes Bolt refactoring and dependency updates.

👏 Improvements

Bolt refactoring #1560 #1574 #1576

🔧 Dependency Management

Update dependencies #1577

`v5.26.0`

This release brings a preview support for GQL Errors.

With this update, Neo4jException gets the following additional GQL metadata:

GQLSTATUS
GQLSTATUS description
GQL diagnostic record
GQL error cause

The additional metadata is exposed via the following new methods respectively:

String gqlStatus();

String statusDescription();

Map<String, Value> diagnosticRecord();

Optional<Neo4jException> gqlCause();

In addition, the following getters have been added for extracting a vendor-specific classification from the GQL diagnostic record:

Optional<GqlStatusErrorClassification> classification();

Optional<String> rawClassification();

⭐ New Features

Add preview support for GQL Errors #1559

🔧 Dependency Management

Update dependencies #1573

`v5.25.0`

This update includes a general optimisation and dependency updates.

5.25 API documentation

👏 Improvements

Delete results from transaction results holder when fully consumed #1571

🔧 Dependency Management

Update dependencies #1572

`v5.24.0`

This is a planned minor update release that includes improvements and dependency updates.

5.24 API documentation

👏 Improvements

Add host-only factory using default port to ServerAddress #1566
Add NotificationClassification.SCHEMA #1567

🔧 Dependency Management

Update dependencies #1568

`v5.23.0`

This release introduces a Bolt 5.6 support and includes dependency updates.

5.23 API documentation

⭐ New Features

Add Bolt 5.6 #1562

🔧 Dependency Management

Update dependencies #1563

`v5.22.0`

This release introduces a preview support for GQL-status objects and includes dependency updates.

5.22 API documentation

⭐ New Features

Add support for GQL-status objects #1555

🔧 Dependency Management

Update dependencies #1556

`v5.21.0`

This is a planned minor update release that includes dependency updates.

5.21 API documentation

🔧 Dependency Management

Update dependencies #1552

`v5.20.0`

This is a planned minor update release that includes dependency updates.

5.20 API documentation

🔧 Dependency Management

Update dependencies #1550

`v5.19.0`

This release introduces mTLS support preview and includes dependency updates.

5.19 API documentation

⭐ New Features

Introduce mTLS support #1543

🔧 Dependency Management

Update dependencies #1547

`v5.18.0`