Hibernate Reactive

A reactive API for Hibernate ORM, supporting non-blocking database drivers and a reactive style of interaction with the database.

Hibernate Reactive may be used in any plain Java program, but is especially targeted toward usage in reactive environments like Quarkus and Vert.x.

Currently PostgreSQL, MySQL, MariaDB, and Db2 are supported.

Learn more at http://hibernate.org/reactive.

Compatibility

Hibernate Reactive has been tested with:

• Java 8
• PostgreSQL 13
• MySQL 8
• MariaDB 10
• Db2 11.5
• Hibernate ORM 5.4.28.Final
• Vert.x Reactive PostgreSQL Client 3.9.5
• Vert.x Reactive MySQL Client 3.9.5
• Vert.x Reactive Db2 Client 3.9.5
• Quarkus via the Hibernate Reactive extension

Support for SQL Server is coming soon.

Documentation

The Introduction to Hibernate Reactive covers everything you need to know to get started, including:

• setting up a project that uses Hibernate Reactive and the Vert.x reactive SQL client for your database,
• configuring Hibernate Reactive to access your database,
• writing Java code to define the entities of your data model,
• writing reactive data access code using a reactive session, and
• tuning the performance of your program.

We recommend you start there!

Example program

There is a very simple example program in the

example

Quarkus quickstarts

A list of quickstarts for Quarkus is available on GitHub: - Hibernate Reactive with RESTEasy Reactive quickstart - Hibernate Reactive with Vert.x Web Routes quickstart

Or you can generate a new Quarks project that uses the Hibernate Reactive extension and start coding right away.

Gradle build

The project is built with Gradle, but you do not need to have Gradle installed on your machine.

Building

To compile this project, navigate to the

hibernate-reactive

./gradlew compileJava

To publish Hibernate Reactive to your local Maven repository, run:

./gradlew publishToMavenLocal

Building documentation

To build the API and Reference documentation type:

./gradlew assembleDocumentation

You'll find the generated documentation in the subdirectory

release/build/documentation

open release/build/documentation/reference/html_single/index.html
open release/build/documentation/javadocs/index.html

Running tests

To run the tests, you'll need to decide which RDBMS you want to test with, and then get an instance of the test database running on your machine.

By default, the tests will be run against PostgreSQL. To test against MySQL, MariaDB, or Db2, you must explicitly specify

-Pdb=mysql

-Pdb=maria

-Pdb=db2

./gradlew test -Pdb=db2

There are three ways to start the test database.

If you have Docker installed

If you have Docker installed, running the tests is really easy. You don't need to create the test databases manually. Just type:

./gradlew test -Pdocker

Or:

./gradlew test -Pdocker -Pdb=mysql

Or:

./gradlew test -Pdocker -Pdb=maria

Or:

./gradlew test -Pdocker -Pdb=db2

The tests will run faster if you reuse the same containers across multiple test runs. To do this, edit the testcontainers configuration file

.testcontainers.properties

testcontainers.reuse.enable=true

If you already have PostgreSQL installed

If you already have PostgreSQL installed on your machine, you'll just need to create the test database. From the command line, type the following commands:

psql
create database hreact;
create user hreact with password 'hreact';
grant all privileges on database hreact to hreact;

Then run

./gradlew test

hibernate-reactive

If you already have MySQL installed

If you have MySQL installed, you can create the test database using the following commands:

mysql -uroot
create database hreact;
create user hreact identified by 'hreact';
grant all on hreact.* to hreact;

Then run

./gradlew test -Pdb=mysql

hibernate-reactive

If you have Podman

If you have Podman installed, you can start the test database by following the instructions in podman.md.

Limitations

We're working hard to support the full feature set of Hibernate ORM. At present a few limitations remain.

Association mappings

At this time, Hibernate Reactive does not support the following mapping features:

• @ManyToMany

  associations, and
• one-sided

  @OneToMany

  associations without

  mappedBy

  .

Instead, use

@OneToMany(mappedBy=...)

@ManyToOne

Schema export

Automatic update or validation of an existing database schema requires use of JDBC.

Caching

You should not use Hibernate Reactive with a second-level cache implementation which performs blocking IO, for example passivation to the filesystem or distributed replication.