[ + ]

Table of Contents

Micronaut Neo4j

Integration between Micronaut and Neo4j

Version: 6.4.0

1 Introduction

This project includes integration between Micronaut Framework and Neo4j.

2 Release History

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-neo4j/releases

3 Setting up the Neo4j Bolt Driver

Using the CLI

If you are creating your project using the Micronaut CLI, supply the neo4j-bolt feature to configure the Neo4j Bolt driver in your project:

$ mn create-app my-app --features neo4j-bolt

To configure the Neo4j Bolt driver you should first add the neo4j-bolt module to your classpath:

implementation("io.micronaut.neo4j:micronaut-neo4j-bolt")
<dependency>
    <groupId>io.micronaut.neo4j</groupId>
    <artifactId>micronaut-neo4j-bolt</artifactId>
</dependency>

You should then configure the URI of the Neo4j server you wish to communicate with in application.yml:

Configuring neo4j.uri
neo4j:
    uri: bolt://localhost
The neo4j.uri setting should be in the format as described in the Connection URIs section of the Neo4j documentation

Once you have the above configuration in place you can inject an instance of the org.neo4j.driver.v1.Driver bean, which features both a synchronous blocking API and a non-blocking API based on CompletableFuture.

Neo4j Health Checks

When the micronaut-neo4j-bolt module is activated a Neo4jHealthIndicator is activated resulting in the /health endpoint and CurrentHealthStatus interface resolving the health of the Neo4j connection.

See the section on the Health Endpoint for more information.

4 Configuring the Neo4j Bolt Driver

The configuration can be further customized with all the options available using the Neo4jBoltConfiguration class.

The Neo4jBoltConfiguration also exposes all the options for the org.neo4j.driver.v1.Config.ConfigBuilder class.

Below represents an example configuration:

Customizing the Bolt Configuration
neo4j:
    uri: bolt://localhost
    maxConnectionPoolSize: 50
    connectionAcquisitionTimeout: 30s
You can also create a BeanCreatedEventListener bean and listen for the creation of the Neo4jBoltConfiguration to further programmatically customize configuration

5 Neo4j and Testing

Using Testcontainers Neo4j

The recommended mechanism for testing micronaut-neo4j is Testcontainers Neo4j. It utilizes the official docker image provided by Neo4j, Inc.

To use it include the following dependency in your project:

testImplementation("org.testcontainers:neo4j:1.18.3")
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>neo4j</artifactId>
    <version>1.18.3</version>
    <scope>test</scope>
</dependency>

Using the Neo4J Test Harness

Use of the Neo4J Test Harness is deprecated for Micronaut Framework and direct integration for it (i.e. the embedded version mentioned below) will be removed in the next major version of micronaut-neo4j.

You can embed Neo4j for testing by including a dependency on the Neo4j test harness:

testImplementation("org.neo4j.test:neo4j-harness")
<dependency>
    <groupId>org.neo4j.test</groupId>
    <artifactId>neo4j-harness</artifactId>
    <scope>test</scope>
</dependency>

The Neo4j test harness also requires a runtime dependency on javax.annotation and javax.validation

testRuntimeOnly("javax.annotation:javax.annotation-api:1.3.2")
<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version>
    <scope>test</scope>
</dependency>
testRuntimeOnly("javax.validation:validation-api:2.0.1.Final")
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
    <scope>test</scope>
</dependency>

If the Neo4j server is not already running on the configured port an embedded version will be started.

You can configure the options for the embedded Neo4j server using the neo4j.embedded settings exposed by Neo4jBoltConfiguration.

One useful option is ephemeral which ensures the data is cleaned up between test runs. For example in application-test.yml:

Using ephemeral
neo4j:
    embedded:
        ephemeral: true

6 Version Matrix

  • Micronaut Neo4j 6.x uses the Neo4j Java Driver 5.x that adds support for Java 17 runtime versions. To use it in a Micronaut Framework 4 project the version is not required since that is exposed by the BOM.

implementation("io.micronaut.neo4j:micronaut-neo4j-bolt")
<dependency>
    <groupId>io.micronaut.neo4j</groupId>
    <artifactId>micronaut-neo4j-bolt</artifactId>
</dependency>

7 Breaking Changes

This section documents breaking changes between Micronaut Neo4J versions:

Micronaut Neo4J 6.4.0

Micronaut Neo4J is based on Neo4j 5.x, which has breaking changes from Neo4j 3.5.x used by previous versions of Micronaut Neo4J.

For more information, refer to the following Neo4j guides:

Neo4J Java Driver 5.x adds compatibility for Java 17

Neo4J Harness 5.x adds compatibility for Java 17

Starting with Micronaut Framework 4.0.0 the Neo4j Harness requires a runtime dependency on javax.annotation and javax.validation

testRuntimeOnly("javax.annotation:javax.annotation-api:1.3.2")
<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version>
    <scope>test</scope>
</dependency>
testRuntimeOnly("javax.validation:validation-api:2.0.1.Final")
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
    <scope>test</scope>
</dependency>

8 Repository

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-neo4j