Repository files navigation

A reactive API forHibernate ORM, supporting non-blocking databasedrivers and a reactive style of interaction with the database.

Hibernate Reactive may be used in any plain Java program, but isespecially targeted toward usage in reactive environments likeQuarkus andVert.x.

CurrentlyPostgreSQL,MySQL,MariaDB,Db2,CockroachDB,MS SQL Server andOracle are supported.

Learn more athttp://hibernate.org/reactive.

Hibernate Reactive has been tested with:

• Java 17, 21, 24
• PostgreSQL 17
• MySQL 9
• MariaDB 11
• Db2 12
• CockroachDB v25
• MS SQL Server 2025
• Oracle 23
• Hibernate ORM 7.1
• Vert.x Reactive PostgreSQL Client 5.0
• Vert.x Reactive MySQL Client 5.0
• Vert.x Reactive Db2 Client 5.0
• Vert.x Reactive MS SQL Server Client 5.0
• Vert.x Reactive Oracle Client 5.0
• Quarkus via the Hibernate Reactive extension

The exact version of the libraries and images are in thecatalogand in thetooling/docker folder.

TheIntroduction to Hibernate Reactive coverseverything you need to know to get started, including:

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

We recommend you start there!

TheVert.x and Hibernate Reactive How-to explains how to useHibernate Reactive in Vert.x.

TheHibernate Reactive with Panache Guide introducesPanache Reactive, an active record-style API based on Hibernate Reactive.

The directoryexamples contains several small projects showingdifferent features of Hibernate Reactive:

• CRUD operations using the session
• Native queries and stateless session

A collection ofquickstarts for Quarkus is available on GitHub:

• Hibernate Reactive with RESTEasy Reactive
• Hibernate Reactive with Panache
• Hibernate Reactive with Vert.x Web Routes

Or you cangenerate a new Quarkus projectthat uses the Hibernate Reactive extension and start coding right away.

WithJBang you can run one of the examples available in the catalogwithout 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 calledexample), you can do it with:

jbang example@hibernate/hibernate-reactive

or you canopen 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 Testcontainersdb2-reproducer = Template for a test with Db2 using Junit 4, Vert.x Unit and Testcontainersmariadb-reproducer = Template for a test with MariaDB using Junit 4, Vert.x Unit and Testcontainersmysql-reproducer = Template for a test with MySQL using Junit 4, Vert.x Unit and Testcontainerspg-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 donot need to have Gradleinstalled on your machine.

To compile this project, navigate to thehibernate-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 subdirectoryrelease/build/documentation.

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

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

By default, the tests will be run against PostgreSQL. To test againsta different database, you must explicitly specify it using the property-Pdb, as shown in the table below.

It's even possible to run all tests or certain selected tests onall available databases:

./gradlew testAll -PincludeTests=DefaultPortTest

The propertyincludeTests specifies the name of the test to runand may contain the wildcard*. This property is optional, butvery useful, since running all tests on all databases might takea 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. Youdon't need to create the test databases manually. Just type:

./gradlew test -Pdocker

The above command will start an instance of PostgreSQL in a Dockercontainer. You may specify a different database using one of thecommands show in the table below.

The tests will run faster if you reuse the same containers acrossmultiple test runs. To do this, edit the testcontainers configurationfile.testcontainers.properties in your home directory, adding thelinetestcontainers.reuse.enable=true. (Just create the file if itdoesn't already exist.)

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

psqlcreate 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 thehibernate-reactive directory.

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

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

Then run./gradlew test -Pdb=mysql from thehibernate-reactivedirectory.

If you havePodman installed, you can start the testdatabase by following the instructions inpodman.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 fordatabase-generated@Version properties is not yet supported.
• The annotation@org.hibernate.annotations.CollectionId is not yetsupported.
• With Db2:
  • Automatic schema update and validation is not supported.
  • @Lob annotation is not supported - Seethis issue on the vertx-db2-client