Use Arc features in Hibernate extensions for eager startup and active/inactive #48783

yrodiere · 2025-07-04T16:21:20Z

Draft for now.

To do:

Closes Use Arc features in Hibernate extensions for eager startup and active/inactive #43594

Migration guide entry:

== Hibernate ORM

[[hibernate-orm-inactive-fail-fast]]
=== Hibernate ORM usage fails fast if persistence unit is deactivated

In previous versions of Quarkus, when the persistence unit was deactivated (`quarkus.hibernate-orm.active=false`), the application would be allowed to start successfully, but could fail much later upon first access to a Hibernate bean (`EntityManager`, `Session`, `SessionFactory`, ...).

Starting with this version of Quarkus, persistence units that are deactivated will lead to a startup failure if Quarkus can detect they are used:

* Static CDI injection points involving the persistence unit (`@Inject Session session`, `@Inject SessionFactory sessionFactory`, ...) will cause application startup to fail with an explicit, actionable message.
* Dynamic retrieval of the persistence unit (e.g. through `CDI.getBeanContainer()`/`Arc.instance()`, or by injecting an `Instance<Session>`) will not be detected on startup, but will cause an exception to be thrown with an explicit, actionable message.

The <<hibernate-reactive-inactive-fail-fast,Hibernate Reactive>> and <<hibernate-search-inactive-fail-fast,Hibernate Search>> extensions implement a similar behavior for their `Mutiny.SessionFactory`/`SearchSession`/`SearchMapping` CDI beans.

If your application needs to inject a `EntityManager/`Session`/`EntityManagerFactory`/`SessionFactory` or related bean for a persistence unit that can potentially be deactivated or have no URL, you may encounter a startup failure similar to this:

```
io.quarkus.arc.InactiveBeanException: Bean is not active: SYNTHETIC bean [class=org.hibernate.Session, id=QdxvhYUzh5cgfepxgL43K9-OFvU]
Reason: Persistence unit '<default>' was deactivated through configuration properties. To activate the persistence unit, set configuration property 'quarkus.hibernate-orm.active' to 'true' and configure datasource '<default>'. Refer to https://quarkus.io/guides/datasource for guidance.
To avoid this exception while keeping the bean inactive:
	- Configure all extensions consuming this bean as inactive as well, if they allow it, e.g. 'quarkus.someextension.active=false'
	- Make sure that custom code only accesses this bean if it is active
	- Inject the bean with 'Instance<org.hibernate.Session>' instead of 'org.hibernate.Session'
This bean is injected into:
	- io.quarkus.hibernate.orm.config.ConfigActiveFalseStaticInjectionTest$MyBean#session
[...]
```

To avoid this failure, follow the instructions in the exception message.
In particular, consider injecting the problematic bean as an `InjectableInstance` (for example `@Inject InjectableInstance<Session> session`) instead.
You can check whether that bean is active using `.getHandle().getBean().isActive().result()` on the `InjectableInstance`, and retrieve the bean instance using `InjectableInstance#get()`.
See https://quarkus.io/guides/hibernate-orm#persistence-unit-active for an example of such a setup for `Session`.

== Hibernate Reactive

[[hibernate-reactive-inactive-fail-fast]]
=== Hibernate Reactive usage fails fast if persistence unit is deactivated

Starting with this version of Quarkus, Hibernate Reactive persistence units that are deactivated will lead to a startup failure if Quarkus can detect they are used.

See the <<hibernate-orm-inactive-fail-fast,datasources,similar migration guide entry for Hibernate ORM>> for more information.

== Hibernate Search

[[hibernate-search-inactive-fail-fast]]
=== Hibernate Search usage fails fast if persistence unit is deactivated

Starting with this version of Quarkus, Hibernate Search mappings that are deactivated will lead to a startup failure if Quarkus can detect they are used.

See the <<hibernate-orm-inactive-fail-fast,datasources,similar migration guide entry for Hibernate ORM>> for more information.

quarkus-bot · 2025-07-04T16:21:55Z

/cc @gsmet (hibernate-orm)

github-actions · 2025-07-04T17:06:35Z

🎊 PR Preview 28074c2 has been successfully built and deployed to https://quarkus-pr-main-48783-preview.surge.sh/version/main/guides/

Images of blog posts older than 3 months are not available.
Newsletters older than 3 months are not available.

yrodiere · 2025-08-29T14:09:35Z

Hey @Sanne I remember discussing this with you: silently deactivating the PU when the datasource has no URL and proceeding with startup if the PU beans (session, session factory, ...) are not injected anywhere. I remember you had some conceerns, probably because this would be a very breaking change and/or simply inconvenient behavior.

Well, if that was your opinion, I'm starting to think like you. For example in the Panache case, where the session might not even be injected anywhere, this would be pretty bad.

So, I'm rolling this back a bit: I'll only silently deactivate the PU if there are no entity types in the PU (which we intend to make possible through #48732). In that case it's likely that Hibernate ORM is being used as a simple wrapper of JDBC with more convenient querying capabilities (with projections, ...), so I think it makes more sense.

This means in the vast majority of cases we'll get pretty much the same behavior as today, so it's much safer, too.

yrodiere · 2025-09-11T08:41:38Z

Hey @marko-bekhta or @lucamolteni can I please ask one of you review this? If you skip the first commit it's almost a reasonable amount of code (and the vast majority is just tests that look very similar).

EDIT: No need for both of you to review of course :)

marko-bekhta

Thanks! Looks nice 😃 🎉

I had some questions, but feel free to ignore those 😄

...st/java/io/quarkus/hibernate/orm/envers/config/ConfigOrmActiveFalseAndAuditedEntityTest.java

...te/search/orm/elasticsearch/test/configuration/ConfigOrmActiveFalseAndIndexedEntityTest.java

...arkus/hibernate/reactive/config/datasource/MultiplePUAsAlternativesWithBeanProducerTest.java

docs/src/main/asciidoc/datasource.adoc

docs/src/main/asciidoc/hibernate-orm.adoc

...m/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmCdiProcessor.java

...ment/src/test/java/io/quarkus/hibernate/orm/config/ConfigActiveFalseStaticInjectionTest.java

...ve/deployment/src/test/java/io/quarkus/hibernate/reactive/config/NoConfigNoEntitiesTest.java

marko-bekhta · 2025-09-11T10:19:26Z

.../hibernate/search/orm/elasticsearch/deployment/HibernateSearchElasticsearchCdiProcessor.java


-        if (isDefaultPersistenceUnit) {
+        if (PersistenceUnitUtil.isDefaultPersistenceUnit(persistenceUnitName)) {
            configurator.addQualifier(Default.class);
        }


for Search we always add the named qualifiers (just below) and for ORM those seem to be conditional, I wonder if we should be consistent 🤔

I would like to, and if so I'd change what we do in ORM, but that seems out of scope. Want to create an issue?

extensions/hibernate-reactive/deployment/pom.xml

yrodiere

I addressed your comments @marko-bekhta , thank you!

docs/src/main/asciidoc/hibernate-orm.adoc

yrodiere · 2025-09-11T11:55:16Z

docs/src/main/asciidoc/hibernate-orm.adoc

+* Dynamic retrieval of the persistence unit, such as through `CDI.getBeanContainer()`, `Arc.instance()`, or by injecting an `Instance<Session>`, causes an exception to be thrown.
+* Other Quarkus extensions that consume the persistence unit may cause application startup to fail.
+
+In this case, you must also deactivate those other extensions.


I added a small bit of documentation. Should be enough for now?

...bernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/HibernateOrmRecorder.java

...m/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmCdiProcessor.java

...ment/src/test/java/io/quarkus/hibernate/orm/config/ConfigActiveFalseStaticInjectionTest.java

yrodiere · 2025-09-11T12:00:22Z

.../hibernate/search/orm/elasticsearch/deployment/HibernateSearchElasticsearchCdiProcessor.java


-        if (isDefaultPersistenceUnit) {
+        if (PersistenceUnitUtil.isDefaultPersistenceUnit(persistenceUnitName)) {
            configurator.addQualifier(Default.class);
        }


I would like to, and if so I'd change what we do in ORM, but that seems out of scope. Want to create an issue?

extensions/hibernate-reactive/deployment/pom.xml

So that we can more easily see what the next commit changes.

…ate ORM is deactivated

…/inactive

…rnate Reactive too

…n is inactive Only actually attempting to retrieve the bean instance will trigger a failure. Co-Authored-By: marko-bekhta <[email protected]>

quarkus-bot · 2025-09-11T12:34:46Z

Status for workflow `Quarkus Documentation CI`

This is the status report for running Quarkus Documentation CI on commit e5cc8a6.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.

quarkus-bot · 2025-09-11T13:37:28Z

Status for workflow `Quarkus CI`

This is the status report for running Quarkus CI on commit e5cc8a6.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

You can consult the Develocity build scans.

yrodiere · 2025-09-11T13:47:42Z

We're good to go, I just need an approval from someone with push access... @Sanne would you please do that? @marko-bekhta reviewed already and (I think) is happy :)

lucamolteni · 2025-09-11T14:00:28Z

Hey @marko-bekhta or @lucamolteni can I please ask one of you review this? If you skip the first commit it's almost a reasonable amount of code (and the vast majority is just tests that look very similar).

EDIT: No need for both of you to review of course :)

Impressive changes thank you

quarkus-bot bot added area/hibernate-orm Hibernate ORM area/hibernate-reactive Hibernate Reactive labels Jul 4, 2025

yrodiere mentioned this pull request Jul 4, 2025

Keep the Hibernate ORM and Reactive extensions enabled even when no entity is defined #48732

Draft

yrodiere force-pushed the i43594 branch 4 times, most recently from 36159d4 to ee161f6 Compare July 28, 2025 11:55

quarkus-bot bot added area/docstyle issues related for manual docstyle review area/documentation labels Jul 28, 2025

yrodiere force-pushed the i43594 branch 2 times, most recently from 328bc46 to ef96914 Compare July 28, 2025 14:30

quarkus-bot bot added the area/panache label Jul 28, 2025

yrodiere force-pushed the i43594 branch from ef96914 to 39ccec1 Compare August 27, 2025 14:49

yrodiere force-pushed the i43594 branch from 39ccec1 to 40575d4 Compare August 29, 2025 15:05

yrodiere mentioned this pull request Sep 4, 2025

Use Arc features in Hibernate extensions for eager startup and active/inactive #43594

Open

yrodiere force-pushed the i43594 branch from 40575d4 to a106bc4 Compare September 5, 2025 14:49

quarkus-bot bot added the area/hibernate-search Hibernate Search label Sep 5, 2025

yrodiere force-pushed the i43594 branch 7 times, most recently from 9ff633f to f6be893 Compare September 9, 2025 13:40

yrodiere marked this pull request as ready for review September 10, 2025 08:21

This comment has been minimized.

Sign in to view

yrodiere requested a review from marko-bekhta September 10, 2025 16:08

yrodiere requested a review from lucamolteni September 11, 2025 08:41

marko-bekhta reviewed Sep 11, 2025

View reviewed changes

yrodiere force-pushed the i43594 branch from f6be893 to b872bfb Compare September 11, 2025 12:00

yrodiere commented Sep 11, 2025

View reviewed changes

yrodiere and others added 6 commits September 11, 2025 14:02

Refactor tests around active/inactive for Hibernate ORM/Reactive/Search

42b3edc

So that we can more easily see what the next commit changes.

Test that Hibernate Envers and Search don't fail to start when Hibern…

573a221

…ate ORM is deactivated

Use Arc features in Hibernate extensions for eager startup and active…

6b7bf4d

…/inactive

Document and test that persistence units can be deactivated with Hibe…

6175360

…rnate Reactive too

Clarify that injecting Instance<MyBean> won't fail startup if MyBea…

3556595

…n is inactive Only actually attempting to retrieve the bean instance will trigger a failure. Co-Authored-By: marko-bekhta <[email protected]>

Fix typo in Hibernate ORM documentation example

e5cc8a6

yrodiere force-pushed the i43594 branch from b872bfb to e5cc8a6 Compare September 11, 2025 12:02

yrodiere removed the request for review from lucamolteni September 11, 2025 12:38

marko-bekhta approved these changes Sep 11, 2025

View reviewed changes

Use Arc features in Hibernate extensions for eager startup and active/inactive #48783

Are you sure you want to change the base?

Use Arc features in Hibernate extensions for eager startup and active/inactive #48783

Conversation

yrodiere commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

quarkus-bot bot commented Jul 4, 2025

Uh oh!

github-actions bot commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yrodiere commented Aug 29, 2025

Uh oh!

This comment has been minimized.

yrodiere commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

marko-bekhta left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marko-bekhta Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

yrodiere Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yrodiere left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

yrodiere Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yrodiere Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

quarkus-bot bot commented Sep 11, 2025

Status for workflow Quarkus Documentation CI

Uh oh!

quarkus-bot bot commented Sep 11, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Status for workflow Quarkus CI

Uh oh!

yrodiere commented Sep 11, 2025

Uh oh!

lucamolteni commented Sep 11, 2025

Uh oh!

Uh oh!

yrodiere commented Jul 4, 2025 •

edited

Loading

github-actions bot commented Jul 4, 2025 •

edited

Loading

yrodiere commented Sep 11, 2025 •

edited

Loading

Status for workflow `Quarkus Documentation CI`

quarkus-bot bot commented Sep 11, 2025 •

edited by github-actions bot

Loading

Status for workflow `Quarkus CI`