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, Db2, CockroachDB, MS SQL Server and Oracle are supported.
Learn more at http://hibernate.org/reactive.
Hibernate Reactive has been tested with:
- Java 11, 17, 18
- PostgreSQL 15
- MySQL 8
- MariaDB 10
- Db2 11.5
- CockroachDB 22.1
- MS SQL Server 2019
- Oracle 21.3
- Hibernate ORM 6.2.7.Final
- Vert.x Reactive PostgreSQL Client 4.4.4
- Vert.x Reactive MySQL Client 4.4.4
- Vert.x Reactive Db2 Client 4.4.4
- Vert.x Reactive MS SQL Server Client 4.4.4
- Vert.x Reactive Oracle Client 4.4.4
- Quarkus via the Hibernate Reactive extension
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!
The Vert.x and Hibernate Reactive How-to explains how to use Hibernate Reactive in Vert.x.
The Hibernate Reactive with Panache Guide introduces Panache Reactive, an active record-style API based on Hibernate Reactive.
The directory examples
contains several small projects showing
different features of Hibernate Reactive:
A collection of quickstarts for Quarkus is available on GitHub:
- Hibernate Reactive with RESTEasy Reactive
- Hibernate Reactive with Panache
- Hibernate Reactive with Vert.x Web Routes
Or you can generate a new Quarkus project that uses the Hibernate Reactive extension and start coding right away.
With JBang you can run one of the examples available in the catalog without having to clone the repository or setup the project in the IDE. Once you have downloaded JBang, the list of examples is available via:
jbang alias list hibernate/hibernate-reactive
If you want to run one of the example (in this case the one called example
), you can do it with:
jbang example@hibernate/hibernate-reactive
or you can open it in your editor (IntelliJ IDEA in this case) with:
jbang edit --open=idea testcase@hibernate/hibernate-reactive
You can also generate and run a db-specific test. See available templates using: jbang template list
cockroachdb-reproducer = Template for a test with CockroachDB using Junit 4, Vert.x Unit and Testcontainers
db2-reproducer = Template for a test with Db2 using Junit 4, Vert.x Unit and Testcontainers
mariadb-reproducer = Template for a test with MariaDB using Junit 4, Vert.x Unit and Testcontainers
mysql-reproducer = Template for a test with MySQL using Junit 4, Vert.x Unit and Testcontainers
pg-reproducer = Template for a test with PostgreSQL using Junit 4, Vert.x Unit and Testcontainers
Example for PostgreSQL:
- Generate java test from template:
jbang init --template=pg-reproducer pgTest.java
- Run the test:
jbang pgTest.java
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
a different database, you must explicitly specify it using the property
-Pdb
, as shown in the table below.
Database | Command |
---|---|
PostgreSQL | ./gradlew test -Pdb=pg |
MySQL | ./gradlew test -Pdb=mysql |
MariaDB | ./gradlew test -Pdb=maria |
DB2 | ./gradlew test -Pdb=db2 |
SQL Server | ./gradlew test -Pdb=mssql |
Oracle | ./gradlew test -Pdb=oracle |
It's even possible to run all tests or certain selected tests on all available databases:
./gradlew testAll -PincludeTests=DefaultPortTest
The property includeTests
specifies the name of the test to run
and may contain the wildcard *
. This property is optional, but
very useful, since running all tests on all databases might take
a lot of time.
To enable logging of the standard output streams, add the property
-PshowStandardOutput
.
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
The above command will start an instance of PostgreSQL in a Docker container. You may specify a different database using one of the commands show in the table below.
Database | Command |
---|---|
PostgreSQL | ./gradlew test -Pdocker -Pdb=pg |
MySQL | ./gradlew test -Pdocker -Pdb=mysql |
MariaDB | ./gradlew test -Pdocker -Pdb=maria |
DB2 | ./gradlew test -Pdocker -Pdb=db2 |
SQL Server | ./gradlew test -Pdocker -Pdb=mssql |
Oracle | ./gradlew test -Pdocker -Pdb=oracle |
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;
alter user hreact createdb;
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 have Podman installed, you can start the test database by following the instructions in podman.md.
We're working hard to support the full feature set of Hibernate ORM. At present several minor limitations remain.
- The annotation
@org.hibernate.annotations.Source
for database-generated@Version
properties is not yet supported. - The annotation
@org.hibernate.annotations.CollectionId
is not yet supported. - With Db2:
- Automatic schema update and validation is not supported.
@Lob
annotation is not supported - See this issue on the vertx-db2-client