Migration Guide 3.7

Table of Contents

• REST Client ⚙️ ✅
• JPA / Hibernate ORM
  • Upgrade to Hibernate ORM 6.4
  • Static metamodel annotation processor (hibernate-jpamodelgen) can no longer be used as a provided dependency ⚙️ ✅
• Hibernate Search
  • Upgrade to Hibernate Search 7.0
  • Database schema changed for outbox-polling system tables
  • quarkus-hibernate-search-orm-coordination-outbox-polling was renamed ⚙️ ✅
• Scheduler - OpenTelemetry Tracing
• Okhttp/Okio versions not enforced anymore
• Infinispan
• Insecure HTTP port is disabled when mTLS client authentication is required
• Stork

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

REST Client ⚙️ ✅

As part of the renaming of the RESTEasy Reactive extensions that will be spread across several releases, we renamed the quarkus-rest-client* extensions (client extensions for RESTEasy Classic) to quarkus-resteasy-client*, which makes it clearer that it is the client counterpart of quarkus-resteasy.

Relocations have been put into place to not break your applications but we recommend that you adjust your applications already as these particular artifacts (quarkus-rest-client*) will be switched to RESTEasy Reactive in Quarkus 3.9.

The following table summarizes the changes:

Old name	New name
quarkus-rest-client	quarkus-resteasy-client
quarkus-rest-client-jackson	quarkus-resteasy-client-jackson
quarkus-rest-client-jaxb	quarkus-resteasy-client-jaxb
quarkus-rest-client-jsonb	quarkus-resteasy-client-jsonb
quarkus-rest-client-mutiny	quarkus-resteasy-client-mutiny

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:

• Compatibility with some older database versions was dropped.

  See here for supported versions.

• The HQL !=/<> operators no longer allow comparing against null

• Numeric literals are now interpreted as defined in Jakarta Persistence 3.2

See the Hibernate ORM migration guides for more details:

• here for migration from 6.2 to 6.3

• here for migration from 6.3 to 6.4

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.

With Maven:

<build>
    <plugins>
        [...]
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.12.0</version> <!-- Necessary for proper dependency management in annotationProcessorPaths -->
            <configuration>
                <annotationProcessorPaths>
                    <path>
                        <groupId>org.hibernate.orm</groupId>
                        <artifactId>hibernate-jpamodelgen</artifactId>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        [...]
    </plugins>
</build>

Note	Make sure you’re using Maven Compiler Plugin 3.12.0 or later: older versions didn’t handle dependency management for annotationProcessorPath entries, forcing developers to set the version of Hibernate ORM manually, even if they were using the Quarkus BOM.

With Gradle:

dependencies {
    annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen"
}

Hibernate Search

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 Quarkus extension for Hibernate Search with 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.

Okhttp/Okio versions not enforced anymore

Okhttp and Okio versions are not enforced by the Quarkus BOM anymore.

Make sure you define the versions in your build files if you are using any of these dependencies.

Infinispan

The quarkus-test-infinispan-client artifact has been retired. We don’t think it was used outside of the Quarkus core repository and it wasn’t used anymore even there since the introduction of Dev Services for Infinispan.

Insecure HTTP port is disabled when mTLS client authentication is required

PLain HTTP port is now disabled by default when an mTLS client authentication is required. For example, if you have enabled mTLS with the following configuration:

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=required

Then, attempts to access the Quarkus endpoint over an insecure (not https://) HTTP URL such as http://localhost:8080/service will fail because it has been requested by the server that the client sends a certificate to validate its identity. This mechanism is enforced at the transport level.

This stricter policy has been enforced to avoid unexpected insecure HTTP requests reaching Quarkus applications that do not use the Quarkus Security mTLS authentication mechanism.

If you need to allow insecure HTTP requests when an mTLS client authentication is required then you can enable such requests with quarkus.http.insecure-requests=enabled. However, if it is indeed necessary, it is recommended and simpler to use an mTLs client authentication request mode instead, for example:

quarkus.http.ssl.certificate.key-store-file=server-keystore.jks
quarkus.http.ssl.certificate.key-store-password=the_key_store_secret
quarkus.http.ssl.certificate.trust-store-file=server-truststore.jks
quarkus.http.ssl.certificate.trust-store-password=the_trust_store_secret
quarkus.http.ssl.client-auth=request

Stork

The configurations names stork."service-name".load-balancer or quarkus.stork."service-name".load-balancer are not used anymore to configure the Stork load-balancer. Please use quarkus.stork."service-name".load-balancer.type instead.