Skip to content

Migration Guide 3.7

Yoann Rodière edited this page Dec 4, 2023 · 37 revisions

JPA / Hibernate ORM

Upgrade to Hibernate ORM 6.4

The Quarkus extensions for Hibernate ORM was upgraded to Hibernate ORM 6.4.

Here are the most impactful changes:

See the Hibernate ORM migration guides for more details:

Static metamodel annotation processor (hibernate-jpamodelgen) can no longer be used as a provided dependency

Some projects used to apply the hibernate-jpamodelgen annotation processor with a dependency, like so:

  <dependencies>
      <!-- ... -->
      <!-- THIS IS WRONG! See below -->
      <dependency>
          <groupId>org.hibernate.orm</groupId>
          <artifactId>hibernate-jpamodelgen</artifactId>
          <scope>provided</scope>
          <version>6.2.4</version> <!-- Optional, may be managed by a BOM -->
      </dependency>
      <!-- ... -->
  </dependencies>

This is actually wrong for several reasons, one of them being that dependencies of the annotation processor may not be handled correctly.

With Hibernate ORM 6.4, this annotation processor now has more dependencies, and the snippet above will fail, most likely with an error about an ANTLR class not being available.

Applications using Hibernate ORM 6.4+ (and thus Quarkus 3.7+) should register the hibernate-jpamodelgen annotation processor using the proper solution depending on their building tool.

<properties>
    <hibernate-orm.version>6.4.0.Final</hibernate-orm.version>
</properties>
<build>
    <plugins>
        [...]
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>...</version>
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.hibernate.orm</groupId>
                        <artifactId>hibernate-jpamodelgen</artifactId>
                        <version>${hibernate-orm.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        [...]
    </plugins>
</build>
dependencies {
    annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen"
}
Note

One downside of this "proper" solution is that Maven won’t apply dependency management to annotationProcessorPath entries, so you’ll have to set the version of Hibernate ORM manually, even if you use the Quarkus BOM.

This should be solved in Maven Compiler Plugin version 3.12.0; see https://issues.apache.org/jira/browse/MCOMPILER-391.

Upgrade to Hibernate Search 7.0

The Quarkus extensions for Hibernate Search was upgraded to Hibernate Search 7.0.

Here are the most impactful changes:

  • The values accepted by configuration properties quarkus.hibernate-search-orm.coordination.entity-mapping.outbox-event.uuid-type and quarkus.hibernate-search-orm.coordination.entity-mapping.agent.uuid-type changed:

    • uuid-binary is deprecated in favor of binary

    • uuid-char is deprecated in favor of char

  • The default value for quarkus.hibernate-search-orm.elasticsearch.query.shard-failure.ignore changed from true to false, meaning that Hibernate Search will now throw an exception if at least one shard failed during a search operation.

    To get the previous behavior set this configuration property explicitly to true.

    Note this configuration property must be set for each Elasticsearch backend, if you define multiple backends.

  • The complement operator (~) in the regular expression predicate was removed with no alternative to replace it.

  • The corresponding Hibernate Search dependencies no longer have an -orm6 suffix in their artifact ID; for example applications will now depend on hibernate-search-mapper-orm instead of hibernate-search-mapper-orm-orm6.

See the Hibernate Search 7.0 migration guide for more details.

Database schema changed for outbox-polling system tables

The Quarkus extension for Hibernate Search with outbox-polling relies on system tables in your database, and the schema of these system tables changed.

See this section of the Hibernate Search migration guide for information on how to migrate your database schema if you were using that extension.

quarkus-hibernate-search-orm-coordination-outbox-polling was renamed

  • The extension’s artifact ID was renamed from quarkus-hibernate-search-orm-coordination-outbox-polling to quarkus-hibernate-search-orm-outbox-polling

  • The base package in the corresponding Hibernate Search dependency changed from org.hibernate.search.mapper.orm.coordination.outboxpolling to org.hibernate.search.mapper.orm.outboxpolling

Scheduler - OpenTelemetry Tracing

The integration of OpenTelemetry Tracing and Scheduler has been refactored. Previously, only @Scheduled methods had a new io.opentelemetry.api.trace.Span associated automatically when tracing is enabled, i.e. when the quarkus.scheduler.tracing.enabled configuration property is set to true and the OpenTelemetry extension is present. Since Quarkus 3.7, all scheduled jobs (including the jobs scheduled programmatically) have a Span associated automatically when tracing is enabled. Furthermore, the unique job identifier (specified with Scheduled.identity() or JobDefinition) is used as a span name. Previously, the span names followed the <simpleclassname>.<methodName> format.

Current version

Migration Guide 3.18

Next version in main

Migration Guide 3.19

Clone this wiki locally