Hibernate Reactive is a reactive API for Hibernate ORM, supporting non-blocking database drivers and a reactive style of interaction with the database.
Hibernate Reactive works with the same annotations and most of the configuration described in the xref:quarkus-hibernate-orm.adoc[Hibernate ORM guide]. This guide will only focus on what's specific for Hibernate Reactive.
Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.
The solution is located in the hibernate-reactive-quickstart directory.
Setting up and configuring Hibernate Reactive
When using Hibernate Reactive in Quarkus, you need to:
-
add your configuration settings in
application.properties -
annotate your entities with
@Entityand any other mapping annotations as usual
Other configuration needs have been automated: Quarkus will make some opinionated choices and educated guesses.
Add the following dependencies to your project:
-
the Hibernate Reactive extension:
io.quarkus:quarkus-hibernate-reactive -
the Reactive SQL client extension for the database of your choice; the following options are available:
-
quarkus-reactive-pg-client: the client for PostgreSQL or CockroachDB -
quarkus-reactive-mysql-client: the client MySQL or MariaDB -
quarkus-reactive-mssql-client: the client for Microsoft SQL Server -
quarkus-reactive-db2-client: the client for IBM Db2
-
<dependencies>
<!-- Hibernate Reactive dependency -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-hibernate-reactive</artifactId>
</dependency>
<!-- Reactive SQL client for PostgreSQL -->
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-reactive-pg-client</artifactId>
</dependency>
</dependencies>
Annotate your persistent objects with @Entity,
then add the relevant configuration properties in application.properties:
application.properties# datasource configuration
quarkus.datasource.db-kind = postgresql
quarkus.datasource.username = quarkus_test
quarkus.datasource.password = quarkus_test
quarkus.datasource.reactive.url = vertx-reactive:postgresql://localhost/quarkus_test (1)
# drop and create the database at startup (use `update` to only update the schema)
quarkus.hibernate-orm.database.generation=drop-and-create
| 1 | The only different property from a Hibernate ORM configuration |
Note that these configuration properties are not the same ones as in your typical Hibernate Reactive configuration file. They will often map to Hibernate Reactive configuration properties but could have different names and don’t necessarily map 1:1 to each other.
Also, Quarkus will set many Hibernate Reactive configuration settings automatically, and will often use more modern defaults.
Configuring Hibernate Reactive using the standard persistence.xml configuration file is not supported.
|
Please, see section Hibernate Reactive configuration properties for the list of properties you can set in application.properties.
A Mutiny.SessionFactory will be created based on the Quarkus datasource configuration as long as the Hibernate Reactive extension is listed among your project dependencies.
The dialect will be selected based on the Reactive SQL client - unless you set one explicitly.
You can then happily inject your Mutiny.SessionFactory:
@ApplicationScoped
public class SantaClausService {
@Inject
Mutiny.SessionFactory sf; (1)
public Uni<Void> createGift(String giftDescription) {
Gift gift = new Gift();
gift.setName(giftDescription);
return sf.withTransaction(session -> session.persist(gift)) (2)
}
}
| 1 | Inject your session factory and have fun |
| 2 | .withTransaction() will automatically flush at commit |
Make sure to wrap methods modifying your database (e.g. session.persist(entity)) within a transaction.
|
@Entity
public class Gift {
private Long id;
private String name;
@Id
@SequenceGenerator(name = "giftSeq", sequenceName = "gift_id_seq", allocationSize = 1, initialValue = 1)
@GeneratedValue(generator = "giftSeq")
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
}
To load SQL statements when Hibernate Reactive starts, add an import.sql file in your src/main/resources/ directory.
This script can contain any SQL DML statements.
Make sure to terminate each statement with a semicolon.
This is useful to have a data set ready for your tests or demos.
Hibernate Reactive configuration properties
There are various optional properties useful to refine your session factory or guide Quarkus' guesses.
When no properties are set, Quarkus can typically infer everything it needs to setup Hibernate Reactive and will have it use the default datasource.
The configuration properties listed here allow you to override such defaults, and customize and tune various aspects.
Hibernate Reactive uses the same properties you would use for Hibernate ORM. You will notice that some properties
contain jdbc in the name but there is not JDBC in Hibernate Reactive, these are simply legacy property names.
|
Want to start a PostgreSQL server on the side with Docker?
This will start a non-durable empty database: ideal for a quick experiment! |
CDI integration
If you are familiar with using Hibernate Reactive in Quarkus, you probably already have injected the Mutiny.SessionFactory using CDI:
@Inject
Mutiny.SessionFactory sessionFactory;
This will inject the Mutiny.SessionFactory of the default persistence unit.
You can also inject an instance of Uni<Mutiny.Session> using the exact same mechanism:
@Inject
Uni<Mutiny.Session> session;
Limitations and other things you should know
Quarkus does not modify the libraries it uses; this rule applies to Hibernate Reactive as well: when using this extension you will mostly have the same experience as using the original library.
But while they share the same code, Quarkus does configure some components automatically and inject custom implementations for some extension points; this should be transparent and useful but if you’re an expert of Hibernate Reactive you might want to know what is being done.
Here’s a list of things to pay attention when using Hibernate Reactive in Quarkus:
-
it’s not possible to configure multiple persistence units at the moment
-
it’s not configurable via a
persistence.xmlfile -
integration with the Envers extension is not supported
-
transaction demarcation cannot be done using
javax.transaction.Transactional
Simplifying Hibernate Reactive with Panache
The Hibernate Reactive with Panache extension facilitates the usage of Hibernate Reactive by providing active record style entities (and repositories) and focuses on making your entities trivial and fun to write in Quarkus.