Support @Transactional for Hibernate Reactive #51063

lucamolteni · 2025-11-17T16:14:46Z

Introduces a new extension enabling @transactional annotation support for
Hibernate Reactive. This allows developers to use familiar transaction semantics
with reactive database operations.

Key implementation details:

New quarkus-reactive-transactions extension with dedicated CDI interceptors
TransactionalContextPool wraps the SQL client pool to lazily open transactions
based on Vert.x context flags set by the @transactional interceptor
TransactionalInterceptorBase manages the complete transaction lifecycle
(begin, commit, rollback) within the reactive Uni pipeline
TransactionalContextConnection wrapper prevents premature connection closure
before transaction commit/rollback
OpenedSessionState refactored from Panache to centrally manage session
lifecycle and caching (possibly to be reused in Panache as well)
Validation prevents mixing @transactional with @WithTransaction and
@WithSessionOnDemand annotations to avoid conflicting transaction semantics
Disable JTA interceptor execution for methods returning Uni to prevent
mixups

Limitations:

Currently supports only Transactional.TxType.REQUIRED, other TxType values
throw UnsupportedOperationException

Dependencies updated:

hibernate-orm.version → 7.2.0.CR1
hibernate-reactive.version → 3.2.0-SNAPSHOT

Fixes #47462
Fixes #47698

Support @transactional on Reactive methods as well
Injection of Mutiny.Session as injectable bean

@transactional

Fixes: quarkusio#47698 Introduces a new extension enabling @transactional annotation support for Hibernate Reactive. This allows developers to use familiar transaction semantics with reactive database operations. Key implementation details: * New hibernate-reactive-transactions extension with dedicated CDI interceptors * TransactionalContextPool wraps the SQL client pool to lazily open transactions based on Vert.x context flags set by the @transactional interceptor * TransactionalInterceptorBase manages the complete transaction lifecycle (begin, commit, rollback) within the reactive Uni pipeline * TransactionalContextConnection wrapper prevents premature connection closure before transaction commit/rollback * OpenedSessionState refactored from Panache to centrally manage session lifecycle and caching (possibly to be reused in Panache as well) * Validation prevents mixing @transactional with @WithTransaction and @WithSessionOnDemand annotations to avoid conflicting transaction semantics * Disable JTA interceptor execution for methods returning Uni to prevent mixups Limitations: * Currently supports only Transactional.TxType.REQUIRED, other TxType values throw UnsupportedOperationException Dependencies updated: * hibernate-orm.version → 7.2.0.CR1 * hibernate-reactive.version → 3.2.0-SNAPSHOT

@transactional

Renamed module name from hibernate-reactive-transactions => quarkus-reactive-transactions Removed panache dependency from transaction (was test) Adds quarkus-reactive-transactions dependency to hibernate-reactive-panache-common/runtime and quarkus-reactive-transactions-deployment dependency to hibernate-reactive-panache/deployment to support the relocated tests. Move @transactional mixing tests to hibernate-reactive-panache

import static io.quarkus.hibernate.reactive.transactions.runtime.TransactionalInterceptorBase.isUniReturnType; import static io.quarkus.hibernate.reactive.transactions.runtime.TransactionalInterceptorBase.proceedUni; Moved the WITH_TRANSACTION_METHOD_KEY constant inside Transaction module Moved the SESSION_ON_DEMAND_KEY constant inside Transaction module

quarkus-bot · 2025-11-17T16:16:00Z

/cc @gsmet (hibernate-orm)

lucamolteni · 2025-11-17T16:19:06Z

@yrodiere @FroMage this is the first Draft of the @transactional support on Reactive

Here's what it's currently missing on my todo list

Reduplicate the Vert.x context every time with have a @transactional annotation (be aware that doing this will break putting stuff inside the Vert.x context) -
TransactionalInterceptorBase: Handle checked exception vs runtime exception differently according to the spec copy the logic from io/quarkus/narayana/jta/runtime/interceptor/TransactionalInterceptorBase.java:363
withTransactionalSessionOnDemand check that there's no other session opened by session delegators for another PU
withTransactionalSessionOnDemand check that there's no statelessSession opened by statelessSession delegators
MixReactiveTransactional (old annotation)
MixStatelessStatefulSessionTest
In TransactionalContextPool we create a new transaction if needed, but nobody updates the reference inside the MutinySession (currentTransaction) so if a user access it it seems like transaction is null, while instead it's running
Test extra transactional state
Test also when you put @transactional on a method where you pass a Uni as a parameter, I'm not sure it works. If that's the case it'll break the experience for the users

lucamolteni · 2025-11-18T08:13:43Z

Also @DavideD take a look at this please

yrodiere

I didn't go through the tests but I feel they're WIP anyway, so I felt it would be better to just send this.

yrodiere · 2025-11-18T09:18:29Z

extensions/hibernate-reactive-transactions/deployment/pom.xml

+        <artifactId>quarkus-reactive-transactions-parent</artifactId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+    <artifactId>quarkus-reactive-transactions-deployment</artifactId>


The directory name is hibernate-reactive-transactions and that's wrong, it should be reactive-transactions to match the artifact ID.

Though I'm wondering if it makes sense to have this artifact ID if you're putting Hibernate-specific things and tests in here...

I wonder how much of this module can be moved directly to the Hibernate Reactive extensions?

Couldn't this module be just about the interceptor + setting some "transaction context", with the rest of the implementation, and tests, living directly in the Hibernate Reactive module?

Perhaps this is something that will be easier to discuss live... Feel free to hit me with a meeting if so.

Good question. This could be in the quarkus-hibernate-reactive module, no?

yrodiere · 2025-11-18T09:22:28Z

...ime/src/main/java/io/quarkus/hibernate/reactive/runtime/OpenedSessionsStateStatefulImpl.java

+
+    @Override
+    protected Mutiny.Session newSessionMethod(Mutiny.SessionFactory sessionFactory) {
+        return sessionFactory.createSession();


This requires Davide to backport his patch to open connections lazily, correct?

yrodiere · 2025-11-18T09:26:39Z

...src/main/java/io/quarkus/hibernate/reactive/runtime/customized/TransactionalContextPool.java

+            return delegate.getConnection()
+                    .compose(connection -> {
+                        LOG.tracef("New connection, about to start transaction: %s", connection);
+                        return connection.begin().map(t -> {


As discussed, if we open transactions "under the hood", we will need Hibernate Reactive to correctly detect that and expose Mutiny.Session#currentTransaction accordingly. Do you have an issue for that in Reactive already?

yrodiere · 2025-11-18T15:14:29Z

...rm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/StatelessSessionLazyDelegator.java

+    @Override
+    public SharedStatelessSessionBuilder statelessWithOptions() {
+        return delegate.get().statelessWithOptions();
+    }
+
+    @Override
+    public SharedSessionBuilder sessionWithOptions() {
+        return delegate.get().sessionWithOptions();
+    }
+


While the change 100% makes sense, I'm curious: how did you detect it was needed... ?

yrodiere · 2025-11-18T15:15:45Z

...orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java

    private static final String ALLOW_ENHANCEMENT_AS_PROXY = "hibernate.bytecode.allow_enhancement_as_proxy";

-    private static final CoreMessageLogger LOG = messageLogger(FastBootMetadataBuilder.class);
+    private static final CoreMessageLogger LOG = CoreMessageLogger.CORE_LOGGER; // TODO Luca review this


Review this indeed :)

Was this needed simply for the upgrade to Hibernate Reactive 3.2 or 4.2? If so we need to move it to a separate commit, at least, and eventually to a separate PR (like #50519)

yrodiere · 2025-11-20T16:51:04Z

...src/main/java/io/quarkus/hibernate/reactive/runtime/customized/TransactionalContextPool.java

+                            Transaction transaction = connection.transaction();
+                            LOG.tracef("Transaction started: %s", transaction);
+                            Vertx.currentContext().putLocal(CURRENT_TRANSACTION_KEY, transaction);
+                            return new TransactionalContextConnection(connection);


With this wrapper, a call to close is a no-op.

Did you make sure the underlying connection gets closed after commit/rollback, somehow?

yrodiere · 2025-11-20T16:53:02Z

...src/main/java/io/quarkus/hibernate/reactive/runtime/customized/TransactionalContextPool.java

+        }
+    }
+
+    private static final Logger LOG = Logger.getLogger(TransactionalContextPool.class);


Just a general warning, take it or ignore it: some people here feel strongly about code style, and I've never seen code in Quarkus where attributes/constants are in the middle of methods, instead of at the top of the file. You might want to fix that.

Yeah, move it up :) I had the same observation.

yrodiere · 2025-11-20T17:02:38Z

.../src/main/java/io/quarkus/narayana/jta/runtime/interceptor/TransactionalInterceptorBase.java

+        // Disable Interceptor on Reactive (uni) methods
+        // in The Reactive transaction module only REQUIRED is supported so far
+        if (ic.getMethod().getReturnType().equals(Uni.class)) {
+            log.debugf("method is annoted @Transactional but returns a Uni<?>, JTA transactions will be disabled");
+            return true;
+        }
+        return false;


I have a feeling we may come to regret this method of detection...

For example:

What if a method is meant to be actually "blocking transactional", but returns a Uni that when subscribed to, will execute code on the event loop?

What if someone (wrongly) adds @Transactional to a method returning a Multi?

Etc.

Could it possibly make sense that, instead of looking at the return type, we check whether we're on an event loop (Context.isOnEventLoopThread()), and if so, we use reactive transactions, otherwise we use blocking transactions?

Then the Reactive interceptor can check the return type and fail if it's not Uni.

I think this would solve the two scenarios above.

Good question, but I think most of the logic in Quarkus equates Uni with reactive. So this seems like a fine first rule.

What if someone (wrongly) adds @transactional to a method returning a Multi

We could detect that and throw at build time.

yrodiere · 2025-11-20T17:04:27Z

extensions/panache/hibernate-reactive-panache-common/runtime/pom.xml

+        <dependency>
+            <groupId>io.quarkus</groupId>
+            <artifactId>quarkus-reactive-transactions</artifactId>
+        </dependency>


Shouldn't this be a transitive dependency of quarkus-hibernate-reactive, which this module already depends on?

yrodiere · 2025-11-20T17:06:53Z

integration-tests/hibernate-reactive-transactions/pom.xml

+        <artifactId>quarkus-integration-tests-parent</artifactId>
+        <version>999-SNAPSHOT</version>
+    </parent>
+    <artifactId>quarkus-reactive-transactions-integration-tests</artifactId>


If you make quarkus-reactive-transactions a dependency of quarkus-hibernate-reactive, you can probably avoid this additional module and just test everything in the Hibernate Reactive integration tests.

Bonus points if this allows you to test transactions on multiple databases :)

FroMage · 2025-11-20T13:57:06Z

...orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java

    private static final String ALLOW_ENHANCEMENT_AS_PROXY = "hibernate.bytecode.allow_enhancement_as_proxy";

-    private static final CoreMessageLogger LOG = messageLogger(FastBootMetadataBuilder.class);
+    private static final CoreMessageLogger LOG = CoreMessageLogger.CORE_LOGGER; // TODO Luca review this


These seem like an oversight

FroMage · 2025-11-20T13:57:16Z

...m/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java

 public final class QuarkusProxyFactory implements ProxyFactory {

-    private static final CoreMessageLogger LOG = messageLogger(QuarkusProxyFactory.class);
+    private static final CoreMessageLogger LOG = CoreMessageLogger.CORE_LOGGER; // TODO Luca review this


FroMage · 2025-11-20T13:58:40Z

...runtime/src/main/java/io/quarkus/hibernate/orm/runtime/session/TransactionScopedSession.java


+    @Override
+    public SharedStatelessSessionBuilder statelessWithOptions() {
+        try (SessionResult emr = acquireSession()) {


Not entirely sure why the method below called checkBlocking() and this one not.

FroMage · 2025-11-20T14:00:06Z

...arkus/hibernate/reactive/transactions/deployment/HibernateReactiveTransactionsProcessor.java

+
+    @BuildStep
+    void register(
+            BuildProducer<ReflectiveClassBuildItem> reflectiveClass // TOOD Luca hack to make this build step run


Every build step needs an output otherwise it won't be invoked.

FroMage · 2025-11-20T14:02:00Z

...est/java/io/quarkus/hibernate/reactive/transactions/test/mixing/MixReactiveBlockingTest.java

+    @RunOnVertxContext
+    @Disabled("WIP")
+    public void avoidMixingTransactionalAndWithTransactionTest(UniAsserter asserter) {
+        avoidMixingBlockingEMWithReactiveSessionFactory();


Yeah, this is not how you run HR tests with a vertx context :-/

FroMage · 2025-11-20T15:01:53Z

...src/main/java/io/quarkus/hibernate/reactive/runtime/customized/TransactionalContextPool.java

+        } else {
+            delegate.getConnection(result -> {
+                if (result.failed()) {
+                    handler.handle(result);


Probably should return here, no? Avoid going on further.

FroMage · 2025-11-20T15:04:22Z

...src/main/java/io/quarkus/hibernate/reactive/runtime/customized/TransactionalContextPool.java

+                        return connection.begin().map(t -> {
+                            Transaction transaction = connection.transaction();
+                            LOG.tracef("Transaction started: %s", transaction);
+                            Vertx.currentContext().putLocal(CURRENT_TRANSACTION_KEY, transaction);


This is not the same code as the above other version of getConnection: the handler-based one does not store the tx in the context and does not wrap in a TransactionalContextConnection. Is this normal?

FroMage · 2025-11-20T15:08:44Z

...e/runtime/src/main/java/io/quarkus/hibernate/reactive/runtime/HibernateReactiveRecorder.java

+        } else if (context.getLocal(TRANSACTIONAL_METHOD_KEY) == null) {
+            throw new IllegalStateException("No current Mutiny.Session found"
+                    + "\n\t- no reactive session was found in the Vert.x context and the context was not marked to open a new session lazily"
+                    + "\n\t- a session is opened automatically for JAX-RS resource methods annotated with an HTTP method (@GET, @POST, etc.); inherited annotations are not taken into account"


Is this true, though? This looks like it is only true for @Transactional methods. Unlike ORM (blocking) sessions which are automatically opened (without TX) regardless of whether there's any @Transactional annotation.

FroMage · 2025-11-21T13:47:02Z

...ime/src/main/java/io/quarkus/hibernate/reactive/runtime/OpenedSessionsStateStatefulImpl.java

+
+    @Override
+    protected boolean isSessionOpen(Mutiny.Session session) {
+        return session.isOpen();


Sounds like this method should be in shared session contract @DavideD .

FroMage · 2025-11-21T13:52:19Z

pom.xml

        <bytebuddy.version>1.17.6</bytebuddy.version> <!-- version controlled by Hibernate ORM's needs -->
        <hibernate-models.version>1.0.1</hibernate-models.version> <!-- version controlled by Hibernate ORM's needs -->
-        <hibernate-reactive.version>3.1.8.Final</hibernate-reactive.version> <!-- highly sensitive to Hibernate ORM upgrades -->
+        <hibernate-reactive.version>3.2.0-SNAPSHOT</hibernate-reactive.version> <!-- highly sensitive to Hibernate ORM upgrades -->


What's required from these two upgraded deps?

lucamolteni added 4 commits November 17, 2025 16:55

Support injection for Stateless session as well

d53862c

lucamolteni changed the title ~~47698 bis squash~~ Support @Transactional for Hibernate Reactive Nov 17, 2025

quarkus-bot bot added area/dependencies Pull requests that update a dependency file area/hibernate-orm Hibernate ORM area/hibernate-reactive Hibernate Reactive area/narayana Transactions / Narayana area/panache labels Nov 17, 2025

lucamolteni requested review from FroMage and yrodiere November 17, 2025 16:17

yrodiere reviewed Nov 20, 2025

View reviewed changes

FroMage reviewed Nov 21, 2025

View reviewed changes

Support @Transactional for Hibernate Reactive #51063

Are you sure you want to change the base?

Support @Transactional for Hibernate Reactive #51063

Conversation

lucamolteni commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quarkus-bot bot commented Nov 17, 2025

Uh oh!

lucamolteni commented Nov 17, 2025

Uh oh!

lucamolteni commented Nov 18, 2025

Uh oh!

yrodiere left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lucamolteni commented Nov 17, 2025 •

edited

Loading