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 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 @Entity and 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:

For instance:

pom.xml
<!-- 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>
build.gradle
// Hibernate Reactive dependency
implementation("io.quarkus:quarkus-hibernate-reactive")

Reactive SQL client for PostgreSQL
implementation("io.quarkus:quarkus-reactive-pg-client")

Annotate your persistent objects with @Entity, then add the relevant configuration properties in application.properties:

Example 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:

Example application bean using Hibernate Reactive
@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.
Example of an Entity
@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.

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

string

list of string

Name of the file containing the SQL statements to execute when Hibernate ORM starts. Its default value differs depending on the Quarkus launch mode:

  • In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory and it will be picked up without having to set this property. Pass no-file to force Hibernate ORM to ignore the SQL import file.

  • In production mode, it defaults to no-file. It means Hibernate ORM won’t try to execute any SQL import file by default. Pass an explicit value to force Hibernate ORM to execute the SQL import file.

If you need different SQL statements between dev mode, test (@QuarkusTest) and in production, use Quarkus configuration profiles facility.

application.properties
%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql
%test.quarkus.hibernate-orm.sql-load-script = import-test.sql
%prod.quarkus.hibernate-orm.sql-load-script = no-file

Quarkus supports .sql file with SQL statements or comments spread over multiple lines. Each SQL statement must be terminated by a semicolon.

list of string

import.sql in DEV, TEST ; no-file otherwise

Pluggable strategy contract for applying physical naming rules for database object names. Class name of the Hibernate PhysicalNamingStrategy implementation

string

Pluggable strategy for applying implicit naming rules when an explicit name is not given. Class name of the Hibernate ImplicitNamingStrategy implementation

string

Class name of a custom org.hibernate.boot.spi.MetadataBuilderContributor implementation.

Not all customization options exposed by org.hibernate.boot.MetadataBuilder will work correctly. Stay clear of options related to classpath scanning in particular.

This setting is exposed mainly to allow registration of types, converters and SQL functions.

string

XML files to configure the entity mapping, e.g. META-INF/my-orm.xml. Defaults to META-INF/orm.xml if it exists. Pass no-file to force Hibernate ORM to ignore META-INF/orm.xml.

list of string

META-INF/orm.xml if it exists; no-file otherwise

The default in Quarkus is for 2nd level caching to be enabled, and a good implementation is already integrated for you. Just cherry-pick which entities should be using the cache. Set this to false to disable all 2nd level caches.

boolean

true

Defines the method for multi-tenancy (DATABASE, NONE, SCHEMA). The complete list of allowed values is available in the Hibernate ORM JavaDoc. The type DISCRIMINATOR is currently not supported. The default value is NONE (no multi-tenancy).

string

Defines the name of the datasource to use in case of SCHEMA approach. The datasource of the persistence unit will be used if not set.

string

If hibernate is not auto generating the schema, and Quarkus is running in development mode then Quarkus will attempt to validate the database after startup and print a log message if there are any problems.

boolean

true

Whether statistics collection is enabled. If 'metrics.enabled' is true, then the default here is considered true, otherwise the default is false.

boolean

Whether session metrics should be appended into the server log for each Hibernate session. This only has effect if statistics are enabled (quarkus.hibernate-orm.statistics). The default is false (which means both statistics and log-session-metrics need to be enabled for the session metrics to appear in the log).

boolean

Whether or not metrics are published if a metrics extension is enabled.

boolean

false

Dialect related configuration

Type

Default

Class name of the Hibernate ORM dialect. The complete list of bundled dialects is available in the Hibernate ORM JavaDoc.

Not all the dialects are supported in GraalVM native executables: we currently provide driver extensions for PostgreSQL, MariaDB, Microsoft SQL Server and H2.

string

The storage engine to use when the dialect supports multiple storage engines.

E.g. MyISAM or InnoDB for MySQL.

string

Query related configuration

Type

Default

The maximum size of the query plan cache. see #QueryPlanCache#DEFAULT_QUERY_PLAN_MAX_COUNT

int

2048

Default precedence of null values in ORDER BY clauses.

Valid values are: none, first, last.

none, first, last

none

Database related configuration

Type

Default

The charset of the database. Used for DDL generation and also for the SQL import scripts.

Charset

UTF-8

Whether Hibernate should quote all identifiers.

boolean

false

Select whether the database schema is generated or not. drop-and-create is awesome in development mode. This defaults to 'none', however if Dev Services is in use and no other extensions that manage the schema are present this will default to 'drop-and-create'. Accepted values: none, create, drop-and-create, drop, update, validate.

string

none

If Hibernate ORM should create the schemas automatically (for databases supporting them).

boolean

false

Whether we should stop on the first error when applying the schema.

boolean

false

The default catalog to use for the database objects.

string

The default schema to use for the database objects.

string

JDBC related configuration

Type

Default

The time zone pushed to the JDBC driver.

string

How many rows are fetched at a time by the JDBC driver.

int

The number of updates (inserts, updates and deletes) that are sent by the JDBC driver at one time for execution.

int

Fetching logic configuration

Type

Default

The size of the batches used when loading entities and collections.

-1 means batch loading is disabled.

int

16

The maximum depth of outer join fetch tree for single-ended associations (one-to-one, many-to-one).

A 0 disables default outer join fetching.

int

Caching configuration

Type

Default

The maximum time before an object of the cache is considered expired.

Duration

The maximum number of objects kept in memory in the cache.

long

Discriminator related configuration

Type

Default

Existing applications rely (implicitly or explicitly) on Hibernate ignoring any DiscriminatorColumn declarations on joined inheritance hierarchies. This setting allows these applications to maintain the legacy behavior of DiscriminatorColumn annotations being ignored when paired with joined inheritance.

boolean

false

Additional named persistence units

Type

Default

string

list of string

Name of the file containing the SQL statements to execute when Hibernate ORM starts. Its default value differs depending on the Quarkus launch mode:

  • In dev and test modes, it defaults to import.sql. Simply add an import.sql file in the root of your resources directory and it will be picked up without having to set this property. Pass no-file to force Hibernate ORM to ignore the SQL import file.

  • In production mode, it defaults to no-file. It means Hibernate ORM won’t try to execute any SQL import file by default. Pass an explicit value to force Hibernate ORM to execute the SQL import file.

If you need different SQL statements between dev mode, test (@QuarkusTest) and in production, use Quarkus configuration profiles facility.

application.properties
%dev.quarkus.hibernate-orm.sql-load-script = import-dev.sql
%test.quarkus.hibernate-orm.sql-load-script = import-test.sql
%prod.quarkus.hibernate-orm.sql-load-script = no-file

Quarkus supports .sql file with SQL statements or comments spread over multiple lines. Each SQL statement must be terminated by a semicolon.

list of string

import.sql in DEV, TEST ; no-file otherwise

Pluggable strategy contract for applying physical naming rules for database object names. Class name of the Hibernate PhysicalNamingStrategy implementation

string

Pluggable strategy for applying implicit naming rules when an explicit name is not given. Class name of the Hibernate ImplicitNamingStrategy implementation

string

Class name of a custom org.hibernate.boot.spi.MetadataBuilderContributor implementation.

Not all customization options exposed by org.hibernate.boot.MetadataBuilder will work correctly. Stay clear of options related to classpath scanning in particular.

This setting is exposed mainly to allow registration of types, converters and SQL functions.

string

XML files to configure the entity mapping, e.g. META-INF/my-orm.xml. Defaults to META-INF/orm.xml if it exists. Pass no-file to force Hibernate ORM to ignore META-INF/orm.xml.

list of string

META-INF/orm.xml if it exists; no-file otherwise

The default in Quarkus is for 2nd level caching to be enabled, and a good implementation is already integrated for you. Just cherry-pick which entities should be using the cache. Set this to false to disable all 2nd level caches.

boolean

true

Defines the method for multi-tenancy (DATABASE, NONE, SCHEMA). The complete list of allowed values is available in the Hibernate ORM JavaDoc. The type DISCRIMINATOR is currently not supported. The default value is NONE (no multi-tenancy).

string

Defines the name of the datasource to use in case of SCHEMA approach. The datasource of the persistence unit will be used if not set.

string

If hibernate is not auto generating the schema, and Quarkus is running in development mode then Quarkus will attempt to validate the database after startup and print a log message if there are any problems.

boolean

true

Dialect related configuration

Type

Default

Class name of the Hibernate ORM dialect. The complete list of bundled dialects is available in the Hibernate ORM JavaDoc.

Not all the dialects are supported in GraalVM native executables: we currently provide driver extensions for PostgreSQL, MariaDB, Microsoft SQL Server and H2.

string

The storage engine to use when the dialect supports multiple storage engines.

E.g. MyISAM or InnoDB for MySQL.

string

Query related configuration

Type

Default

The maximum size of the query plan cache. see #QueryPlanCache#DEFAULT_QUERY_PLAN_MAX_COUNT

int

2048

Default precedence of null values in ORDER BY clauses.

Valid values are: none, first, last.

none, first, last

none

Database related configuration

Type

Default

The charset of the database. Used for DDL generation and also for the SQL import scripts.

Charset

UTF-8

boolean

false

Select whether the database schema is generated or not. drop-and-create is awesome in development mode. This defaults to 'none', however if Dev Services is in use and no other extensions that manage the schema are present this will default to 'drop-and-create'. Accepted values: none, create, drop-and-create, drop, update, validate.

string

none

If Hibernate ORM should create the schemas automatically (for databases supporting them).

boolean

false

Whether we should stop on the first error when applying the schema.

boolean

false

The default catalog to use for the database objects.

string

The default schema to use for the database objects.

string

JDBC related configuration

Type

Default

The time zone pushed to the JDBC driver.

string

How many rows are fetched at a time by the JDBC driver.

int

The number of updates (inserts, updates and deletes) that are sent by the JDBC driver at one time for execution.

int

Fetching logic configuration

Type

Default

The size of the batches used when loading entities and collections.

-1 means batch loading is disabled.

int

16

The maximum depth of outer join fetch tree for single-ended associations (one-to-one, many-to-one).

A 0 disables default outer join fetching.

int

Caching configuration

Type

Default

The maximum time before an object of the cache is considered expired.

Duration

The maximum number of objects kept in memory in the cache.

long

Discriminator related configuration

Type

Default

Existing applications rely (implicitly or explicitly) on Hibernate ignoring any DiscriminatorColumn declarations on joined inheritance hierarchies. This setting allows these applications to maintain the legacy behavior of DiscriminatorColumn annotations being ignored when paired with joined inheritance.

boolean

false

Database scripts related configuration

Type

Default

Select whether the database schema DDL files are generated or not. Accepted values: none, create, drop-and-create, drop, update, validate.

string

none

Filename or URL where the database create DDL file should be generated.

string

Filename or URL where the database drop DDL file should be generated.

string

Logging configuration

Type

Default

Show SQL logs and format them nicely. Setting it to true is obviously not recommended in production.

boolean

false

Format the SQL logs if SQL log is enabled

boolean

true

Whether JDBC warnings should be collected and logged.

boolean

depends on dialect

If set, Hibernate will log queries that took more than specified number of milliseconds to execute.

long

Logging configuration

Type

Default

Logs SQL bind parameters. Setting it to true is obviously not recommended in production.

boolean

false

Show SQL logs and format them nicely. Setting it to true is obviously not recommended in production.

boolean

false

Format the SQL logs if SQL log is enabled

boolean

true

Whether JDBC warnings should be collected and logged.

boolean

depends on dialect

If set, Hibernate will log queries that took more than specified number of milliseconds to execute.

long

Database scripts related configuration

Type

Default

Select whether the database schema DDL files are generated or not. Accepted values: none, create, drop-and-create, drop, update, validate.

string

none

Filename or URL where the database create DDL file should be generated.

string

Filename or URL where the database drop DDL file should be generated.

string

About the Duration format

The format for durations uses the standard java.time.Duration format. You can learn more about it in the Duration#parse() javadoc.

You can also provide duration values starting with a number. In this case, if the value consists only of a number, the converter treats the value as seconds. Otherwise, PT is implicitly prepended to the value to obtain a standard java.time.Duration format.

Want to start a PostgreSQL server on the side with Docker?

docker run --rm --name postgres-quarkus-hibernate -e POSTGRES_USER=quarkus_test \
           -e POSTGRES_PASSWORD=quarkus_test -e POSTGRES_DB=quarkus_test \
           -p 5432:5432 postgres:14.1

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.xml file

  • 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.