Migration Guide 3.24

Table of Contents

• Jakarta Persistence / Hibernate ORM
  • Upgrade to Hibernate ORM 7.0 / Jakarta Persistence 3.2
  • API changes
  • Behavior changes
  • DDL/schema changes
  • Annotation processor artifact relocation
  • CDI restrictions for Hibernate ORM components
  • Minimum database versions
• Hibernate Reactive
  • Upgrade to Hibernate Reactive 3.0
  • API changes
  • Minimum database versions
• Hibernate Search
  • Upgrade to Hibernate Search 8.0
• Elasticsearch
• Dev Services

Note	We highly recommend the use of quarkus update to update to a new version of Quarkus. Items marked below with ⚙️ ✅ are automatically handled by quarkus update.

Jakarta Persistence / Hibernate ORM

Upgrade to Hibernate ORM 7.0 / Jakarta Persistence 3.2

The Quarkus extension for Hibernate ORM was upgraded to Hibernate ORM 7.0 / Jakarta Persistence 3.2.

Hibernate ORM 7.0 is for the most part backwards-compatible with Hibernate ORM 6.6, and comes with [many improvements and new features, as well as a switch from the LGPL license to ASL 2](https://docs.jboss.org/hibernate/orm/7.0/whats-new/whats-new.html).

However, as with any major version, a few breaking changes are to be expected. Below are the ones most likely to affect existing applications.

Refer to the Hibernate ORM 7.0 migration guide for more information.

API changes

• Various deprecated Session methods have been removed (or, in some cases, deprecated) in favor of JPA equivalents. In particular:

• ⚙️ ✅ : load(…​) without a lock option ⇒ getReference(…​), get(…​) ⇒ find(…​), delete(…​) ⇒ remove(…​), save(…​) ⇒ persist(…​), update(…​) ⇒ merge(…​)

• load(…​) with a lock option ⇒ find(…​), saveOrUpdate(…​) ⇒ persist (new entity) / merge (persisted, then detached entity).

• Various deprecated annotations have been removed in favor of JPA equivalents. In particular: @Table = @jakarta.persistence.Table, @Where/@WhereJoinTable ⇒ @SQLRestriction/@SQLJoinTableRestriction, @OrderBy ⇒ @SQLOrder or @jakarta.persistence.OrderBy, @Index ⇒ @jakarta.persistence.Index, @IndexColumn ⇒ @OrderColumn.

• ⚙️ ✅ (in part): Hibernate’s @Cascade and CascadeType are deprecated in favor of JPA equivalents (e.g. @OneToMany(cascade = …​)).

• Proxy customization changed significantly. If you were using @Proxy, consider `@ConcreteProxy instead, or taking advantage of Session#getReference/Hibernate#unproxy as necessary.

• org.hibernate.Metamodel was removed in favor of org.hibernate.metamodel.model.domain.JpaMetamodel.

• UserType and CompositeType had some method signature change to no longer refer to internal/SPI types.

• Various JDBC types were moved to an internal package. Use @JdbcTypeCode instead of @JdbcType to map your attributes to these types.

• LockOptions was deprecated; impacted methods have alternatives involving LockMode.

Behavior changes

• Many misplaced mapping annotations will now result in an exception, instead of being ignored. This includes for example conflicting @Basic/@ManyToOne annotations on the same attribute, but also using attribute converters on @Id/@Version/associations/etc., which was never supported and was effectively ignored.

• StatelessSession now takes advantage of the second-level cache.

• StatelessSession no longer complies with quarkus.hibernate-orm.jdbc.statement-fetch-size. Instead, you can use explicit batch operations such as insertMultiple().

• Some ambiguous query strings are now disallowed. This should mainly impact type-unsafe query creation, when not passing a class to Session#createQuery, or when using Panache to create a query. Relevant query strings are those without a select clause, but with a (non-fetch) join. For example from Person p left join p.address should become one of from Person p, select p, a from p left join p.address a, or from p left join fetch p.address, depending on the desired behavior.

• Native queries now return java.time types instead of java.sql types for date/time values in the absence of specific type instructions.

DDL/schema changes

Quoting behavior, which suffered from a regression in Hibernate ORM 6.x, was fixed in 7.0 as part of HHH-16516. Custom database initialization script, in particular on H2, may need to be adapted to avoid use of quotes.

The following changes will require updating the database schema, and manually updating data:

• Basic arrays (e.g. String[]) are now mapped to proper array structures in database instead of being serialized as binary data. This behavior can be reverted by setting quarkus.hibernate-orm.unsupported-properties."hibernate.type.preferred_array_jdbc_type" to VARBINARY.

The following changes should not require a database schema or data update, as SQL generated by Hibernate should to work even with an older schema:

• char/Character attributes are mapped to varchar(1) instead of char(1).

• On Oracle and Microsoft SQL Server, timestamp attributes have a different default sub-second precision.

• On Oracle, float/double attributes are mapped to binary_float/binary_double instead of float(p)/real/double precision types.

Annotation processor artifact relocation

Hibernate ORM 7.0 changes the Maven coordinates of its annotation processor responsible for the generation of the static metamodel and Jakarta Data repositories from org.hibernate.orm:hibernate-jpamodelgen to org.hibernate.orm:hibernate-processor. Make sure to update your annotationProcessorPath in Maven, or annotationProcessor instruction in Gradle.

Additionally, the annotation processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor is now deprecated in favor of org.hibernate.processor.HibernateProcessor. If your build script was explicitly referring to the processor by name, e.g. with the annotationProcessors tag of maven-compiler-plugin, make sure to replace the deprecated processor name with the new one.

CDI restrictions for Hibernate ORM components

Some pluggable components, that are potentially retrieved before CDI is initialized, can no longer be CDI beans. This includes in particular:

• org.hibernate.type.descriptor.jdbc.JdbcType

• org.hibernate.type.descriptor.java.BasicJavaType

• org.hibernate.type.descriptor.java.JavaType

• org.hibernate.usertype.UserType

• org.hibernate.usertype.UserCollectionType

• org.hibernate.usertype.CompositeUserType

• org.hibernate.type.descriptor.java.MutabilityPlan

• org.hibernate.metamodel.spi.EmbeddableInstantiator

• org.hibernate.generator.Generator and its subclasses org.hibernate.id.IdentifierGenerator, org.hibernate.generator.AnnotationBasedGenerator, etc.

• org.hibernate.envers.RevisionListener

If you need to provide a custom implementation of such components, and need access to CDI within that implementation, consider retrieving other beans when first needed, using Arc.container().instance(OtherBean.class).get().

Minimum database versions

As with every new version of Hibernate ORM, the minimum required version of databases was bumped to the oldest version still supported by their respective vendor.

See here for details on the current minimum versions.

Hibernate Reactive

Upgrade to Hibernate Reactive 3.0

The Quarkus extension for Hibernate Reactive was upgraded to Hibernate Reactive 3.0.

Hibernate Reactive 3.0 is for the most part backwards-compatible with Hibernate Reactive 2.4, and comes with improvements and new features, like Hibernate ORM does.

However, as with any major version, a few breaking changes are to be expected. You will find the breaking changes inherited from Hibernate ORM above. Below are the ones that are specific to Hibernate Reactive.

API changes

• The ReactiveIdentifierGenerator API changed in various ways. Implementations will need to be rewritten according to the new API.

Minimum database versions

Hibernate Reactive has the same minimum database version requirements as Hibernate ORM. See Minimum database versions for details.

Hibernate Search

Upgrade to Hibernate Search 8.0

The Quarkus extensions for Hibernate Search were upgraded to Hibernate Search 8.0.

Hibernate ORM 8.0 is for the most part backwards-compatible with Hibernate Search 7.2, and comes with many improvements and new features, in particular a static metamodel

However, as with any major version, a few breaking changes are to be expected. Below are the ones most likely to affect existing applications.

Refer to the the Hibernate Search 8.0 migration guide for more information.

• Deprecated classes have been removed in favor of their recommended alternatives, in particular org.hibernate.search.mapper.orm.massindexing.MassIndexingMonitor ⇒ org.hibernate.search.mapper.pojo.massindexing.MassIndexingMonitor.

• MassIndexingMonitor#addToTotalCount is now deprecated in favor of the more flexible MassIndexingMonitor#typeGroupMonitor(..)

• multi() methods in the projection DSL are deprecated in favor of .list()/.set()/sortedSet()/collector(…​).

• Logging categories have been overhauled. See here for a list of available categories. In particular, the org.hibernate.search.elasticsearch.request logging category, used for logging every request sent to Elasticsearch, has been renamed to org.hibernate.search.elasticsearch.client.request.

• Many Search DSL interfaces now have an extra SR type argument to accomodate for the new static metamodel. This mostly affects *Step interfaces which should generally not be imported in application code.

• The format of mass indexing logs has changed — for the better, as more information is presented in a more condensed format.

Elasticsearch

Default connection pool sizes have been bumped to provide a better experience with Hibernate Search, in particular when mass indexing:

• quarkus.elasticsearch.max-connections now defaults to 40 instead of 20.

• quarkus.elasticsearch.max-connections-per-route now defaults to 20 instead of 10.

Dev Services

Several Dev Services default images have been updated:

• Elasticsearch from 8.18 to 9.0

• OpenSearch from 2.16 to 3.0

Note	You can configure Quarkus explicitly to use a specific image for each Dev Service, e.g. see here for Elasticsearch/OpenSearch.