-
Notifications
You must be signed in to change notification settings - Fork 3k
Migration Guide 3.29
Note
|
We highly recommend the use of Items marked below with ⚙️ ✅ are automatically handled by |
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 anInstance<Session>
) will not be detected on startup, but will cause an exception to be thrown with an explicit, actionable message.
The Hibernate Reactive and 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
.
Quarkus will now start Hibernate ORM even if no Hibernate/JPA entities are defined, provided the Hibernate ORM extension is in the classpath and the persistence unit’s datasource is configured (URL set, …). This allows running native queries through Hibernate ORM in particular.
To forcefully disable Hibernate ORM at build time even if the extension is in your classpath, set quarkus.hibernate-orm.enabled
to false
.
To only prevent Hibernate ORM from starting at runtime (e.g. in certain deployments only), set quarkus.hibernate-orm.active
or quarkus.hibernate-orm."persistence-unit-name".active
to false
.
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 similar migration guide entry for Hibernate ORM for more information.
Quarkus will now start Hibernate Reactive even if no Hibernate/JPA entities are defined, provided the Hibernate Reactive extension is in the classpath and the persistence unit’s (reactive) datasource is configured (URL set, …). This allows running native queries through Hibernate Reactive in particular.
To forcefully disable Hibernate ORM/Reactive at build time even if the extension is in your classpath, set quarkus.hibernate-orm.enabled
to false
.
To only prevent Hibernate ORM/Reactive from starting at runtime (e.g. in certain deployments only), set quarkus.hibernate-orm.active
or quarkus.hibernate-orm."persistence-unit-name".active
to false
.
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 similar migration guide entry for Hibernate ORM for more information.
Quarkus changes the defaults for the following Elasticsearch client configuration properties:
-
quarkus.hibernate-search-[orm|standalone].elasticsearch.max-connections
will be40
by default, instead of20
-
quarkus.hibernate-search-[orm|standalone].elasticsearch.max-connections-per-route
will be20
by default, instead of10
This is done to match the change in Hibernate Search itself that aims to prevent a potential consumption of all connections by the indexing queues, leaving no available connections for search requests.
To keep the previous default Elasticsearch configuration, set the following configuration properties
(pick either orm
or standalone
variant depending on the Hibernate Search extension used):
quarkus.hibernate-search-[orm|standalone].elasticsearch.max-connections=20
quarkus.hibernate-search-[orm|standalone].elasticsearch.max-connections-per-route=10
We fixed some cases where an error thrown from a section helper was not correctly propagated, i.e. rendering of a template could result in a timeout instead of a runtime exception. As a result, the methods that trigger rendering (such as TemplateInstance#render()
) now throw a TemplateException
with the original runtime exception as the cause instead of the runtime exception itself.