Hibernate NoSQL

Hibernate NoSQL extends Hibernate ORM by providing connectors and dialects for NoSQL databases.

Caution

This is early work. All contributions welcome.

Building from sources

The build requires at least JDK 25, and produces Java 17 bytecode.

Hibernate uses Gradle as its build tool. See the Gradle Primer section below if you’re new to Gradle.

Contributors should read the Contributing Guide.

See the guides for setting up IntelliJ or Eclipse as your development environment.

Gradle Primer

The Gradle build tool has excellent documentation.

• Gradle User Guide is a typical user guide in that it follows a topical approach to describing all of the capabilities of Gradle.

• Gradle DSL Guide is unique and excellent in quickly getting up to speed on certain aspects of Gradle.

Here we summarize the features you’ll need to get started in this project.

Note	The project has a Gradle Wrapper. The rest of the section will assume execution via the wrapper.

Executing Tasks

To print a list of available build tasks, execute:

./gradlew tasks

To execute a task across all modules, simply execute the task from the root directory.

cd hibernate-nosql
./gradlew build

Gradle visits each subproject and executes the task if the subproject defines it.

To execute a task in a specific module, either:

• cd into that module directory and execute the task, or

• explicitly qualify the task name with the name of the module.

For example, to run the tests for the hibernate-nosql-core module from the root directory you could type:

./gradlew hibernate-nosql-core:test

Common tasks

The common tasks you might use in building Hibernate include:

build

Assembles (jars) and tests this project

compile

Performs all compilation tasks including staging resources from both main and test

jar

Generates a jar archive with all the compiled classes

test

Runs the tests

publishToMavenLocal or pTML

Installs the project jar to your local Maven cache at ~/.m2/repository. Note that Gradle never uses this, but it can be useful for testing a build with other local Maven-based builds.

clean

Cleans the build directory

Testing and databases

Testing Hibernate against an embedded h2 database is easy. Just run:

./gradlew test

To run against another database:

1. start the database using podman or docker, and then

2. run the tests with the correct profile for that database.

Using profiles

The Hibernate build defines several database testing profiles in local.databases.gradle. A profile may be activated by name using the db build property which can be passed either:

• as a JVM system property -Ddb=…​, or

• as a Gradle project property -Pdb=…​.

Examples below use the Gradle project property.

gradle clean build -Pdb=neo4j

To run a test from your IDE, you need to ensure the property expansions happen. Use the following command:

gradle clean compile -Pdb=neo4j

NOTE: To run tests against a JDBC driver that is not available via Maven central, add the driver to your local Maven repository (~/.m2/repository) or to a personal Maven repository server.

Starting a test database as a container

If podman or docker is installed, there’s no need to install any database to test Hibernate NoSQL. The script db.sh starts a preconfigured database which can be used for testing.

Simply run the following command:

./db.sh neo4j

Running ./db.sh without an argument prints a list of available database configurations.

By default, ./db.sh kills any previously started database. To keep multiple databases running, use --keep-orphans or -k:

./db.sh -k neo4j
./db.sh -k milvus

When the database is properly started, run tests with the corresponding profile, for example, -Pdb=neo4j for Milvus. The system property dbHost configures the IP address of your docker host.

The command for running tests might look like the following:

./gradlew test -Pdb=postgresql "-DdbHost=192.168.99.100"

The following table illustrates a list of commands for various databases that can be tested locally.

Database	Start database	Run tests
H2	-	./gradlew test -Pdb=h2
Neo4j	./db.sh neo4j	./gradlew test -Pdb=neo4j
Milvus	./db.sh milvus	./gradlew test -Pdb=milvus

Stopping a test database

To stop a container, use the stop command. For example:

podman stop mariadb

Substitute docker for podman if appropriate.

Continuous Integration

See MAINTAINERS.md for information about CI.