Chapter 1. Migrating applications to Red Hat build of Quarkus 3.27

• Quarkus Migration guide 3.26: legacy config classes support is gone
• Quarkus Sunsetting legacy config classes blog

• To migrate, replace conditional build steps as follows:

  • Previously used code:

    @BuildStep(onlyIf = IsDevelopment.class)
    JsonRPCProvidersBuildItem createJsonRPCService() {
        return new JsonRPCProvidersBuildItem(...);
    }

    Copy to Clipboard Toggle word wrap

  • Updated code:

    @BuildStep
    JsonRPCProvidersBuildItem createJsonRPCService() {
        return new JsonRPCProvidersBuildItem(...);
    }

    Copy to Clipboard Toggle word wrap

• Type: String
• Default value: prod
• Environment variable: QUARKUS_TEST_INTEGRATION_TEST_PROFILE
• Configuration timing: Fixed at build time

• Update your application dependencies to remove Derby JDBC drivers
• Update your application.properties or application.yaml to configure a different database
• Migrate your existing Derby database schema and data to the new database

• Elasticsearch version 9.1
• OpenSearch version 3.1

• API changes

  • Deprecated Session methods have been removed or replaced by JPA equivalents.

    To apply changes marked as "Automatic", run the automatic update process described in the Migrating applications to Red Hat build of Quarkus 3.27 guide, otherwise manually perform any additional steps.

    Expand

    Deprecated Session method	New JPA equivalent	Update process
    load(…​) without a lock option	getReference(…​)	Automatic
    get(…​)	find(…​)	Automatic
    delete(…​)	remove(…​)	Automatic
    save(…​)	persist(…​)	Automatic
    update(…​)	merge(…​)	Manual
    load(…​) with a lock option	find(…​)	Manual
    saveOrUpdate(…​)	persist (new entity) / merge (persisted, then detached entity)	Manual

    Show more
    Note

    When migrating from an update method to a merge method, be aware of the following differences:

    • merge returns an entity instance attached to the persistence context. Ensure that you use that entity and discard the one passed as an argument.
    • To ensure proper merging, merge can load the entity. When using merge on multiple entities in succession, N+1 select issues might occur. To avoid this issue, load all entities in the session before the merge call, for example, by using Session#findMultiple.

    To apply this change, manually perform any additional steps described in this release note.

    For more information, see Hibernate ORM Defer to JPA.

  • Deprecated annotations have been removed or replaced by JPA equivalents. To view the impacted annotations, see Hibernate ORM Annotations.

  • @Cascade and CascadeType are deprecated and replaced by JPA equivalents such as @OneToMany(cascade = …​).

    To apply this change, run the automatic update process described in the Migrating applications to Red Hat build of Quarkus 3.27 guide.

  • Proxy customization has changed. If you were using @Proxy, consider @ConcreteProxy instead, or use the Session#getReference or Hibernate#unproxy methods. For more information, see Hibernate ORM Replace @Proxy.
  • org.hibernate.Metamodel was removed and replaced by org.hibernate.metamodel.model.domain.JpaMetamodel.
  • The UserType and CompositeType method signatures changed to no longer refer to internal or Service Provider Interface (SPI) types. For more information, see Hibernate ORM UserType and CompositeUserType changes.
  • Various JDBC types were moved to an internal package. To map your attributes to these types, use @JdbcTypeCode instead of @JdbcType.
  • The LockOptions class was deprecated; impacted methods have alternatives involving LockMode. Some deprecated features of the LockOptions class have also been removed. For more information, see Hibernate ORM LockOptions.
  • The Session#getLobHelper method is deprecated. Use Hibernate#getLobHelper instead. For more information, see Hibernate ORM Session#getLobHelper.

• Behavior changes

  • Stricter annotation validation

    Misplaced mapping annotations now raise exceptions instead of being ignored. Examples include conflicting @Basic and @ManyToOne annotations on the same attribute, or the use of attribute converters on @Id and @Version. For more information, see Hibernate ORM Domain model validations.

  • Second-level cache usage

    StatelessSession now uses the second-level cache by default. This change impacts migrating applications that use second-level cache and StatelessSession. For more information, see Hibernate ORM StatelessSession and second-Level cache.

  • Batch operation changes

    StatelessSession does not respect the quarkus.hibernate-orm.jdbc.statement-batch-size setting. Because StatelessSession operations are designed to execute immediately, implicit batch operations are not required. Instead, you can use explicit batch operations such as 'insertMultiple()'. For more information, see Hibernate ORM StatelessSession and JDBC batching.

  • Query validation

    Ambiguous query strings are no longer accepted. This mainly affects type-unsafe queries, when not passing a class to Session#createQuery, or when using Panache to create a query. Queries without a select clause, but with a non-fetch join, must now specify the intended behavior. For more information, see Hibernate ORM Query with implicit SELECT and no explicit result type.

  • Changes to types returned for date and time values by native queries

    Previously, java.sql types were used to represent date and time types returned by a native query. Now, native queries return java.time types in the absence of specific type instructions. For more information, see Hibernate ORM Temporal types returned by native queries.

• Minimum database versions

  The minimum required database versions have been updated to use the oldest version still supported by the respective vendor.

  In particular, note the following updates:

  • IBM DB2: minimum version updated from 10.5 to 11.1
  • MariaDB: minimum version updated from 10.4 to 10.6
  • Microsoft SQL Server: minimum version updated from 11.0 (2012) to 12.0 (2014)

  • PostgreSQL: minimum version updated from 12.0 to 13.0

    For more information about current minimum versions, see Hibernate ORM Supported dialects.

• MySQL/MariaDB storage engine

  Using quarkus.hibernate-orm.dialect.storage-engine to set the MySQL/MariaDB storage engine has been deprecated. Use quarkus.hibernate-orm.dialect.mariadb.storage-engine=…​ or quarkus.hibernate-orm.dialect.mysql.storage-engine=…​ instead.

• DDL/schema changes

  • The custom database initialization script, in particular on H2 databases, might need to change to avoid the use of quotes.
  • Basic arrays are now mapped to proper array structures in a database instead of being serialized as binary data. You can revert this behavior by setting quarkus.hibernate-orm.unsupported-properties."hibernate.type.preferred_array_jdbc_type" to VARBINARY. Otherwise, if your entity mapping includes arrays, updates to the database schema and a manual update of data are needed. For more information, see Hibernate ORM Array mapping changes.
  • char/Character attributes are now 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 and double attributes are mapped to binary_float and binary_double instead of float(p), real, or double precision types. For more information, see Hibernate ORM Changes affecting DDL.

• Annotation processor changes

  • The Maven artifact for the Hibernate ORM annotation processor has changed from org.hibernate.orm:hibernate-jpamodelgen to org.hibernate.orm:hibernate-processor. In Maven, update the annotationProcessorPath.

  • The annotation processor org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor is deprecated in favor of org.hibernate.processor.HibernateProcessor.

    To apply this change, run the automatic update process described in the Migrating applications to Red Hat build of Quarkus 3.27 guide.

• Contexts and dependency injection (CDI) restrictions for Hibernate ORM components

  • Some pluggable components, that are potentially retrieved before CDI is initialized, can no longer be CDI beans.

    If you need to provide a custom implementation of such components, and need access to CDI within that implementation, consider retrieving other beans by using Arc.container().instance(OtherBean.class).get(). For a list of impacted components, see the Migration guide 3.24.

• JSON/XML mapping

  Previously, Hibernate ORM’s "format mappers" for JSON/XML serialization in the database relied on global REST layer serialization settings by default.

  Now, it is preferred to separate database layer and REST layer serialization to help ensure database format stability and prevent unnecessary migrations. However, because of this, the current release fails by default if the following conditions are met:

  • Your application has a Hibernate mapping involving XML or JSON stored in the database.
  • The XML or JSON serialization settings for the REST layer are customized.

  Should this occur, you can update your database serialization settings:

  • Jackson-based JSON serialization

    If the ObjectMapper customization applied in your application does not affect the format of the JSON stored in the database, bypass that ObjectMapper by specifying quarkus.hibernate-orm.mapping.format.global=ignore.

    Otherwise, implement a custom FormatMapper bean. First, delegate a format mapper to the global REST layer serialization.

    For more information, see the Migration guide 3.26 and the Customizing JSON/XML serialization/deserialization section of the Quarkus "Using Hibernate ORM and Jakarta Persistence" guide.

    Then, take either of the following actions:

    • Continue to use this delegating format mapper if you want to rely on the globally configured ObjectMapper and depend on the REST layer serialization needs.
    • Prepare and test migration scripts to update your JSON data. You can use either Hibernate ORM’s default format or adapt the FormatMapper implementation to format JSON according to your needs.

  • JSON-B-based JSON serialization

    This scenario is identical to that of the Jackson-based mapper. For more information, see the Migration guide 3.26.

  • JAXB-based XML serialization

    The XML serialization format change in Hibernate ORM 7.0 also has an impact. While the Quarkus built-in JAXB-based XML format mapper uses the legacy format, removing or bypassing it with quarkus.hibernate-orm.mapping.format.global=ignore makes the format incompatible.

    To mitigate, create a mapper that delegates to Hibernate ORM’s mapper. For more information, see the Migration guide 3.26.

    Then, take either of the following actions:

    • Continue to use this delegating format mapper if you want to rely on the legacy format.
    • Prepare and test migration scripts to update your XML data. You can use either Hibernate ORM’s default format or adapt the FormatMapper implementation to format XML according to your needs.

• Hibernate ORM 7.0 migration guide
• Hibernate ORM 7.1 migration guide
• Hibernate ORM 7.1 user guide
• Quarkus Migration guide 3.24
• Quarkus Migration guide 3.26
• Quarkus Using Hibernate ORM and Jakarta Persistence guide

• API changes

  The ReactiveIdentifierGenerator API is updated and now extends org.hibernate.generator.Generator, which requires additional methods.

  This change affects users who define a custom identifier generator by using the @GenericGenerator annotation and implement their own generator classes.

  To implement the new API, update custom identifier generators that are defined with @GenericGenerator.

  In the Generator interface, update the following methods:

  • generatedOnExecution(): Return true if the identifier is generated during query execution, or false if it is generated in your application code.
  • getEventTypes(): Specify if the identifier changes during an insert or update operation.

• Minimum database versions

  The quarkus-hibernate-reactive extension aligns its minimum supported database versions with Hibernate ORM 7.1 dialect requirements. For more information about current minimum versions, see Hibernate ORM Supported dialects.

• Deprecated classes are removed in favor of their recommended alternatives. Notably, org.hibernate.search.mapper.orm.massindexing.MassIndexingMonitor has been replaced by org.hibernate.search.mapper.pojo.massindexing.MassIndexingMonitor.
• The MassIndexingMonitor#addToTotalCount method is deprecated and replaced by MassIndexingMonitor#typeGroupMonitor(..)
• multi() methods in the projection DSL are deprecated and replaced by .list()/.set()/sortedSet()/collector(…​).
• Logging categories have been updated. 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. For more information, see List of all available logging categories.
• Search DSL interfaces are enhanced to include an extra SR type argument reference guide .
• The format of mass indexing logs has changed to present more information in a condensed format.
• Metric aggregation countDistinct() is deprecated and replaced by an option in count() aggregation: .count().field(..).distinct().

• Hibernate Search 8.0 migration guide
• Hibernate Search 8.1 migration guide
• Hibernate Search 8.1 reference guide
• Quarkus Use Hibernate Search with Hibernate ORM and Elasticsearch/OpenSearch guide

• Removal of ZooKeeper dependency
• Support for some older protocols or API versions is removed
• Incompatibility with older clients or brokers that rely on deprecated features
• A minimum requirement for Java version 11 for your Quarkus application
• Improvements to client metrics

• Apache Kafka 4.0 documentation
• Quarkus Apache Kafka reference guide

• Quarkus Using OpenTelemetry Metrics guide
• Quarkus Migration guide 3.25: OpenTelemetry metrics

• Sunsetting legacy config classes
• Quarkus Migration guide 3.14
• Migration to @ConfigMapping

A list of the affected modules:

• quarkus-hibernate-orm-rest-data-panache
• quarkus-hibernate-reactive-rest-data-panache
• quarkus-mongodb-rest-data-panache
• spring-data-rest