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, and DB2 are supported.
Hibernate Reactive has been tested with:
- Java 8
- PostgreSQL 12
- MySQL 8
- DB2 11.5
- Hibernate ORM 5.4.20.Final
- Vert.x Reactive PostgreSQL Client 3.9.2
- Vert.x Reactive MySQL Client 3.9.2
- Vert.x Reactive DB2 Client 3.9.2
Support for SQL Server is coming soon.
Integration with Quarkus has been developed and tested but has not yet been released.
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, and
- writing reactive data access code using a reactive session.
We recommend you start there!
There is a very simple example program in the example
directory.
The project is built with Gradle, but you do not need to have Gradle installed on your machine.
To compile this project, navigate to the hibernate-reactive
directory,
and type:
./gradlew compileJava
To publish Hibernate Reactive to your local Maven repository, run:
./gradlew publishToMavenLocal
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
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 or DB2, you must explicitly specify -Pdb=mysql
or -Pdb=db2
,
for example:
./gradlew test -Pdb=db2
There are three ways to start the test database.
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=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
in your home directory, adding the
line testcontainers.reuse.enable=true
. (Just create the file if it
doesn't already exist.)
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
from the hibernate-reactive
directory.
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
from the hibernate-reactive
directory.
If you use Podman, you can start the test database by following the instructions in podman.md.
To run the tests, type ./gradlew test
from the hibernate-reactive
directory.
We're working hard to support the full feature set of Hibernate ORM. At present a few limitations remain.
At this time, Hibernate Reactive does not support the following mapping features:
@ElementCollection
s,@ManyToMany
associations, and- one-sided
@OneToMany
associations withoutmappedBy
.
Instead, use @OneToMany(mappedBy=...)
together with @ManyToOne
for
all associations.
HQL update
and delete
queries which affect multiple tables (due to the
use of TABLE_PER_CLASS
or JOINED
inheritance mapping) are not working.
The query cache is not yet supported.
Note that 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.
You might run into some limitations of the Vert.x DB2 client when using Hibernate Reactive with DB2.