Hibernate Reactive 2.3.1.Final Reference Documentation

Add the following dependency to your project:

Where {version} is the version of Hibernate Reactive you’re using.

You’ll also need to add a dependency for the Vert.x reactive database driver for your database, one of the following options:

Where {vertxSqlClientVersion} is the version of Vert.x compatible with the version of Hibernate Reactive you’re using.

You don’t need to depend on the JDBC driver for your database.

Optionally, you might also add any of the following additional features:

You might also add the Hibernate bytecode enhancer to your Gradle build if you want to use field-level lazy fetching.

There’s an example Gradle build included in the example program.

Hibernate Reactive is configured via the standard JPA persistence.xml document which must be placed, as usual, in the /META-INF directory.

An example persistence.xml file is included in the example program.

The only required configuration that’s really specific to Hibernate Reactive is the persistence <provider> element, which must be explicit:

Otherwise, configuration is almost completely transparent—you can configure Hibernate Reactive pretty much exactly as you would usually configure Hibernate ORM core.

Just like in regular JPA, you should list your entity classes in persistence.xml:

A full list of configuration properties recognized by Hibernate may be found in the documentation for Hibernate ORM. You’ll never need to touch most of these. The properties you do need at this stage are these three:

These configuration properties have jdbc in their names, but of course there’s no JDBC in Hibernate Reactive, and these are simply the legacy property names defined by the JPA specification. In particular, Hibernate Reactive itself parses and interprets the JDBC URL.

The Vert.x database client has built-in connection pooling and prepared statement caching. You might want to control the size of the connection pool:

We’ll learn about more advanced connection pool tuning later, in Tuning the Vert.x pool.

You can have Hibernate Reactive infer your database schema from the mapping annotation you’ve specified in your Java code, and export the schema at initialization time by specifying one or more of the following configuration properties:

This feature is extremely useful for testing.

Schema export uses blocking operations so starting the factory might require special handling when using it. Failing to do so will cause an exception:

You can solve this issue using executeBlocking:

To see the generated SQL as it’s sent to the database, either:

For example, if you’re using Log4J 2 (as above in Optional dependencies), add these lines to your log4j2.properties file:

An example log4j2.properties file is included in the example program.

You can make the logged SQL more readable by enabling one or both of the following settings:

The following properties are very useful for minimizing the amount of information you’ll need to explicitly specify in @Table and @Column annotations which we’ll discuss below in Mapping entity classes:

By default, SQL Server’s char and varchar types don’t accommodate Unicode data. So, if you’re working with SQL Server, you might need to force Hibernate to use the nchar and nvarchar types.

We won’t have much to say about the entity classes here, simply because the principles behind mapping entity classes in Hibernate Reactive, along with the actual mapping annotations you’ll use, are all identical to regular Hibernate ORM and other implementations of JPA.

For example:

You’re quite free to mix and match:

A full list of object/relational mapping annotations may be found in the documentation for Hibernate ORM. Most mapping annotations are already supported in Hibernate Reactive, though there are still a handful of limitations at this time.

When using Hibernate Reactive outside the Quarkus environment, you’ll need to write your entity classes according to the usual JPA conventions, which require:

It’s illegal to access persistent fields from outside the entity class. Therefore, external access to persistent fields must be intermediated via getter and setter methods defined by the entity class.

When you use Hibernate Reactive in Quarkus, these requirements are relaxed, and you can use public fields instead of getters and setters if you prefer.

Entity classes should override equals() and hashCode(). People new to Hibernate or JPA are often confused by exactly which fields should be included in the hashCode(), so please keep the following principles in mind:

It’s OK to include any immutable, non-generated field in the hashcode.

That said, an implementation of equals() and hashCode() based on the generated identifier of the entity can work if you’re careful.

Note that even when you’ve identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data model much easier to change.

One area where the functionality of Hibernate Reactive diverges from plain Hibernate is in the area of id generation. Custom identifier generators written to work with Hibernate ORM and JDBC will not work in the reactive environment.

The standard id generation strategies defined by the JPA specification may be customized using the following annotations:

For example, sequence id generation may be specified like this:

You can find more information in the JPA specification.

If you have very particular requirements, you can check out the Javadoc of ReactiveIdentifierGenerator for information on how to implement your own custom reactive identifier generator.

Hibernate custom types based on the UserType interface are targeted toward use with JDBC, and depend on interfaces defined by JDBC. So Hibernate Reactive features an adaptor that exposes a partial implementation of JDBC to the UserType implementation.

Therefore, some existing UserType implementations will work in Hibernate Reactive, depending upon precisely which features of JDBC they depend on.

You may specify a custom type by annotating a field of an entity class with the Hibernate @Type annotation.

Any JPA AttributeConverter works in Hibernate Reactive. For example:

You’ll need to use one or both of these annotations:

You’ll find more information in the Javadoc for these annotations and in the JPA specification.

When you write persistence logic using Hibernate Reactive, you’ll be working with a reactive Session most of the time. Just to make things a little more confusing for new users, the reactive Session and its related interfaces all come in two flavors:

You’ll need to decide which API you want to use!

These are the most important operations on reactive streams that you’ll need all the time when working with Hibernate Reactive:

In this introduction, our code examples usually use Mutiny. If you’re more familiar with CompletionStage, you can refer to the above table to help you understand the code.

When we use the term reactive stream in this document, we mean:

that is built by the program in order to service a particular request, transaction, or unit of work.

Whatever you decide, the first step to getting a reactive session is to obtain a JPA EntityManagerFactory just as you usually would in plain ol' regular JPA, for example, by calling:

Now, unwrap() the reactive SessionFactory. If you want to use CompletionStages for chaining reactive operations, ask for a Stage.SessionFactory:

Or, if you prefer to use the Mutiny-based API, unwrap() the type Mutiny.SessionFactory:

Reactive sessions may be obtained from the resulting reactive SessionFactory.

Persistence operations are exposed via a reactive Session object. It’s very important to understand that most operations of this interface are non-blocking, and execution of SQL against the database is never performed synchronously. Persistence operations that belong to a single unit of work must be chained by composition within a single reactive stream.

Also remember that a Hibernate session is a lightweight object that should be created, used, and then discarded within a single logical unit of work.

To obtain a reactive Session from the SessionFactory, use withSession():

The resulting Session object is automatically associated with the current reactive stream, and so nested calls to withSession() in a given stream automatically obtain the same shared session.

Alternatively, you may use openSession(), but you must remember to close() the session when you’re done. And you must take great care to only access each session from within exactly one Vert.x context. (See Sessions and Vert.x contexts more on this).

The Session interface has methods with the same names as methods of the JPA EntityManager. You might already be familiar with the following session operations defined by JPA:

If you’re not familiar with these operations, don’t despair! Their semantics are defined in the JPA specification, and in the API documentation, and are explained in innumerable articles and blog posts. But if you already have some experience with Hibernate or JPA, you’re right at home!

Now, here’s where Hibernate Reactive is different: in the reactive API, each of these methods returns its result in a non-blocking fashion via a Java CompletionStage (or Mutiny Uni). For example:

On the other hand, methods with no meaningful return value just return CompletionStage<Void> (or Uni<Void>).

An extremely common mistake when using reactive streams is to forget to chain the return value of a "void-like" method. For example, in the following code, the flush() operation is never executed, because invoke() doesn’t chain its return value to the tip of the stream.

So remember:

The same problem occurs in the following code, but this time it’s remove() that never gets called:

If you already have some experience with reactive programming, there’s nothing new to learn here. But if you are new to reactive programming, just be aware that you’re going to make this mistake, in some form, at least once!

Naturally, the Session interface is a factory for Query instances which allow you to set query parameters and execute queries and DML statements:

That createQuery() method produces a reactive Query, allowing HQL / JPQL queries to be executed asynchronously, always returning their results via a CompletionStage (or Uni):

The Query interface defines the following important operations:

For JPA criteria queries, you must first obtain the CriteriaBuilder using SessionFactory.getCriteriaBuilder(), and execute your query using Session.createQuery().

In Hibernate ORM, a lazy association is fetched transparently when the association is first accessed within a session. In Hibernate Reactive, on the other hand, lazy association fetching is an asynchronous process that produces a result via a CompletionStage (or Uni).

Therefore, lazy fetching is an explicit operation named fetch(), a static method of Stage and Mutiny:

Of course, this isn’t necessary if you fetch the association eagerly.

Sometimes you might need to chain multiple calls to fetch(), for example:

Similarly, field-level lazy fetching—an advanced feature, which is only supported in conjunction with Hibernate’s optional compile-time bytecode enhancer—is also an explicit operation.

To declare a lazy field we usually use the JPA @Basic annotation:

An optional one-to-one association declared @OneToOne(fetch=LAZY) is also considered field-level lazy.

A lazy field is only fetched if we explicitly request it by calling an overloaded version of the fetch() operation:

Note that the field to fetch is identified by a JPA metamodel Attribute.

The withTransaction() method performs work within the scope of a database transaction.

The session is automatically flushed at the end of the transaction.

For a given Session object, nested calls to withTransaction() occur within the same shared transaction context. However, notice that the transaction is a resource local transaction only, delegated to the underlying Vert.x database client, and does not span multiple datasources, nor integrate with JPA container-managed transactions.

For extra convenience, there’s a method that opens a session and starts a transaction in one call:

This is probably the most convenient thing to use most of the time.

When you create a session using withSession() or withTransaction(), it’s automatically associated with the current Vert.x local context, and propagates with the local context, as mentioned above in Obtaining a reactive session. And you’re only allowed to use the session from the thread that owns this local context. If you screw up, and use it from a different thread, you might see this error:

On the other hand, if you use openSession(), you’ll have to manage the association between sessions and contexts yourself. Now, that’s in principle straightforward, but you’d be surprised how often people mess up.

More than a few users are surprised by this restriction. But we insist that it’s completely natural. An atomic operation of the session, from your point of view as a user of the session, is a method like flush(), find(), or getResultList(). Any one of those methods can result in multiple interactions with the database. And between such interactions, the session is simply not in a well-defined state. Reactive streams are a kind of thread, and it’s quite unreasonable to expect that reactive programming should vanish away your concurrency problems in a shimmering puff of pixie dust. That’s not how these things work.

For example, I bet you would like to be able to write code like this:

Well, we’re sorry, but that’s just not allowed. Parallel reactive streams may not share a session. Each stream must have its own session.

What if you need to run a block of code within the scope of a Vert.x context, but the current thread isn’t associated with a Context? One solution is to obtain a Vert.x Context object using getOrCreateContext() and then call runOnContext() to execute the code in that context.

Within the block of code passed to runOnContext(), you’ll be able to use the Hibernate Reactive session associated with the context.

The VertxInstance service defines how Hibernate Reactive obtains an instance of Vert.x. The default implementation just creates one the first time it’s needed. But if your program requires control over how the Vert.x instance is created, or how it’s obtained, you can override the default implementation and provide your own VertxInstance. Let’s consider this example:

One way to register this implementation is to configure Hibernate programmatically, for example:

Alternatively, you could implement the ServiceContributor interface.

To register this ServiceContributor, add a text file named org.hibernate.service.spi.ServiceContributor to /META-INF/services/.

In Basic configuration we already saw how to set the size of the Vert.x database connection pool. When it comes time for performance tuning, you can further customize the pool and prepared statement cache via the following configuration properties:

Finally, for more advanced cases, you can write your own code to configure the Vert.x client by implementing SqlClientPoolConfiguration.

An easy way to improve performance of some transactions with almost no work at all is to turn on automatic DML statement batching. Batching only helps in cases where a program executes many inserts, updates, or deletes against the same table in a single transaction.

All you need to do is set a single property:

(Again, this property has jdbc in its name, but Hibernate Reactive repurposes it for use with the reactive connection.)

Achieving high performance in ORM means minimizing the number of round trips to the database. This goal should be uppermost in your mind whenever you’re writing data access code with Hibernate. The most fundamental rule of thumb in ORM is:

Without question, the most common cause of poorly-performing data access code in Java programs is the problem of N+1 selects. Here, a list of N rows is retrieved from the database in an initial query, and then associated instances of a related entity are fetched using N subsequent queries.

Hibernate provides several strategies for efficiently fetching associations and avoiding N+1 selects:

Of these, you should almost always use outer join fetching. Batch fetching and subselect fetching are only useful in rare cases where outer join fetching would result in a cartesian product and a huge result set. Unfortunately, outer join fetching simply isn’t possible with lazy fetching.

It follows from this tip that you shouldn’t need to use Stage.fetch() or Mutiny.fetch() very often!

Now, we’re not saying that associations should be mapped for eager fetching by default! That would be a terrible idea, resulting in simple session operations that fetch the entire database! Therefore:

It sounds as if this tip is in contradiction to the previous one, but it’s not. It’s saying that you must explicitly specify eager fetching for associations precisely when and where they are needed.

If you need eager fetching in some particular transaction, use:

You can find much more information about association fetching in the documentation for Hibernate ORM.

A classic way to reduce the number of accesses to the database is to use a second-level cache, allowing cached data to be shared between sessions.

Hibernate Reactive supports second-level cache implementations that perform no blocking I/O.

Configuring Hibernate’s second-level cache is a rather involved topic, and quite outside the scope of this document. But in case it helps, we’re testing Hibernate Reactive with the following configuration, which uses EHCache as the cache implementation, as above in Optional dependencies:

If you’re using EHCache, you’ll also need to include an ehcache.xml file that explicitly configures the behavior of each cache region belonging to your entities and collections.

You can find much more information about the second-level cache in the documentation for Hibernate ORM.

Entity instances aren’t automatically evicted from the session cache when they’re no longer needed. (The session cache is quite different to the second-level cache in this respect!) Instead, they stay pinned in memory until the session they belong to is discarded by your program.

The methods detach() and clear() allow you to remove entities from the session cache, making them available for garbage collection. Since most sessions are rather short-lived, you won’t need these operations very often. And if you find yourself thinking you do need them in a certain situation, you should strongly consider an alternative solution: a stateless session.

An arguably-underappreciated feature of Hibernate is the StatelessSession interface, which provides a command-oriented, more bare-metal approach to interacting with the database.

You may obtain a reactive stateless session from the SessionFactory:

A stateless session:

For a stateless session, you’re always working with detached objects. Thus, the programming model is a bit different:

In certain circumstances, this makes stateless sessions easier to work with, but with the caveat that a stateless session is much more vulnerable to data aliasing effects, since it’s easy to get two non-identical Java objects which both represent the same row of a database table.

In particular, the absence of a persistence context means that you can safely perform bulk-processing tasks without allocating huge quantities of memory. Use of a StatelessSession alleviates the need to call:

When using a stateless session, you should be aware of the following additional limitations:

Finally, an aspect of behavior under load that we didn’t mention above is row-level data contention. When many transactions try to read and update the same data, the program might become unresponsive with lock escalation, deadlocks, and lock acquisition timeout errors.

There’s two basic approaches to data concurrency in Hibernate:

In the Hibernate community it’s much more common to use optimistic locking, and Hibernate makes that incredibly easy.

That said, there is also a place for pessimistic locks, which can sometimes reduce the probability of transaction rollbacks.

Therefore, the find(), lock(), and refresh() methods of the reactive session accept an optional LockMode. You can also specify a LockMode for a query. The lock mode can be used to request a pessimistic lock, or to customize the behavior of optimistic locking: