Reactive Hibernate Extensions

What it provides

bluetape4k-hibernate-reactive makes Hibernate Reactive’s Mutiny and Stage APIs more convenient from Kotlin. It unwraps a JPA EntityManagerFactory as a reactive SessionFactory, bridges session and transaction callbacks to suspending blocks, and replaces repeated Java Class arguments with reified types for queries and EntityGraphs.

It is not a separate ORM or transaction manager. Session creation and closing, commit and rollback, and query execution remain Hibernate Reactive responsibilities. Choose it when you need Vert.x SQL Client based non-blocking I/O while retaining Hibernate entity mapping.

Decisions before adoption

• Choose Mutiny Uni or Java CompletionStage as the primary API for a use case.
• Make the component that creates the reactive factory responsible for closing it at shutdown.
• Decide whether ORM persistence context and dirty checking are needed or whether direct SQL and row mapping with R2DBC fit better.
• Do not run blocking JDBC, file I/O, or long CPU work in session callbacks running on the Vert.x dispatcher.
• Plan fetch joins, EntityGraphs, fetch profiles, or explicit fetch() calls so lazy associations are not read outside the session.

Dependency

Consumers manage only the central BOM version, not individual Hibernate Reactive or ORM versions.

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k:bluetape4k-hibernate-reactive")
}

Gradle project path: :bluetape4k-hibernate-reactive. Source directory: data/hibernate-reactive.

First transaction

Unwrap the JPA factory as a Mutiny factory, then await reactive work inside withTransactionSuspending.

import io.bluetape4k.hibernate.reactive.mutiny.asMutinySessionFactory
import io.bluetape4k.hibernate.reactive.mutiny.withTransactionSuspending
import io.smallrye.mutiny.coroutines.awaitSuspending

val sessionFactory = entityManagerFactory.asMutinySessionFactory()

val saved = sessionFactory.withTransactionSuspending { session ->
    session.persist(author).awaitSuspending()
    author
}

withTransactionSuspending does not close the factory. Its owner must close it during application shutdown.

API map

Task	Mutiny	Stage	Boundary
Convert a JPA factory	asMutinySessionFactory	asStageSessionFactory	Unwraps the existing provider factory.
Run suspending session work	withSessionSuspending	same name	Hibernate Reactive owns the session lifecycle.
Define commit and rollback scope	withTransactionSuspending	same name	Completion and failure follow upstream withTransaction.
Work without a first-level cache	withStatelessSessionSuspending	same name	Use a regular Session when entity state tracking is required.
Typed entity lookup	findAs<T>	findAs<T>	Mutiny has additional LockModeType and EntityGraph overloads.
Typed query	createSelectionQueryAs<R>	same name	Failures surface through Uni or CompletionStage.
Graph and native mapping	createEntityGraphAs, getResultSetMappingAs	same names	Registered names and result types must match provider mappings.

Learning path

These chapters go beyond an API inventory. Each explains why a boundary matters, gives concrete examples, and links to the 1.11.0 release source and MySQL Testcontainers tests. Readers can move directly from explanation to executable evidence.

1. Choosing and bootstrapping Mutiny or Stage — provider setup, factory unwrapping, and API differences.
2. Session and transaction lifecycle — regular, tenant, and stateless scopes plus factory ownership.
3. Typed queries and fetch plans — reified queries, lazy associations, fetch joins, and EntityGraphs.
4. Using StatelessSession — benefits and limits of work without a first-level cache.
5. Failures, cancellation, and operations — exception propagation, cancellation limits, event loops, and observability.
6. Choosing a persistence technology — conventional Hibernate/JPA, Hibernate Reactive, and R2DBC boundaries.

For first adoption, follow chapters 1, 2, 3, then 5. Read chapter 4 for bulk work and chapter 6 while choosing the persistence layer.

Recommended patterns

Use either Mutiny or Stage consistently within one use case. Place the transaction block around the smallest atomic application-service operation and resolve every lazy association with an explicit fetch plan inside that scope. Reserve stateless sessions for work that does not need a persistence context.

Integrations

The module exposes bluetape4k-hibernate, bluetape4k-mutiny, bluetape4k-vertx, Hibernate Reactive, Mutiny Kotlin, and coroutine bridges as API dependencies. The transitive presence of bluetape4k-hibernate does not make blocking EntityManager or JDBC helpers safe inside a Vert.x session callback.

Hibernate Reactive uses the JPA metamodel generator instead of Querydsl. The Author_ and Book_ test types and Criteria examples show the intended typed-metamodel path.

Configuration

A reactive persistence unit uses org.hibernate.reactive.provider.ReactivePersistenceProvider and may list entities explicitly. The 1.11.0 test XML uses the Jakarta Persistence 3.0 XML schema while the BOM resolves the Jakarta Persistence 3.2 API line. Do not describe the XML schema and library API version as the same setting.

The subordinate dependency versions printed in the module README do not match the 1.11.0 version catalog. Do not copy them into consumer instructions; verify compatibility through the central BOM.

Failure behavior

Exceptions from session work reach the caller. Transaction blocks delegate their boundary to Hibernate Reactive withTransaction; the extension adds no retry or compensation policy. Query syntax, mapping, and lock errors remain provider failures.

The coroutine bridge explicitly rethrows CancellationException. However, the release has no test proving immediate cancellation of an in-flight driver query. Do not promise that cancelling the coroutine immediately cancels its SQL statement.

Operations

Observe Vert.x event-loop delay, connection pool wait and utilization, query latency, transaction rollback, lock timeout, and lazy-fetch counts together. Correlate blocking-call detection and slow queries with the request context and verify factory shutdown completes.

Testing

The representative suites cover Mutiny and Stage factory unwrapping, session and transaction exception propagation, typed queries, EntityGraphs, and stateless work against MySQL Testcontainers. Docker is required and the test configuration disables parallel execution.

./gradlew :bluetape4k-hibernate-reactive:test --no-build-cache --no-configuration-cache

Workshops

No separate workshop is registered yet. MutinySessionFactoryExamples, StageSessionFactoryExamples, both SessionSupportTest classes, and both StatelessSessionExamples classes serve as executable learning material linked from the chapters.

1.11.0 scope

This manual describes only production source and tests in the bluetape4k-projects 1.11.0 tag. The module does not provide schema migration, driver-level SQL cancellation guarantees, Querydsl, or a process-wide retry policy. There are no additional production APIs between 1.11.0 and the current source, but later version manuals must compare again.

Source and tests

• Mutiny SessionFactorySupport.kt
• Mutiny SessionSupport.kt
• Mutiny StatelessSessionSupport.kt
• Stage SessionFactorySupport.kt
• Stage SessionSupport.kt
• MutinyExtrasTest.kt
• StageExtrasTest.kt
• persistence.xml

Release diagrams

These diagrams are loaded directly from README assets published with the 1.11.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

Reactive Extension Structure diagram

Release README: data/hibernate-reactive/README.md

Hibernate Reactive API Structure diagram

Release README: data/hibernate-reactive/README.md

Session Type Comparison diagram

Release README: data/hibernate-reactive/README.md