Skip to content

Migration Guide 3.14

Jump to bottom
Yoann Rodière edited this page Oct 10, 2024 · 29 revisions
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.

JPA / Hibernate ORM

Upgrade to Hibernate ORM 6.6

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

Hibernate ORM 6.6 is largely backwards-compatible with Hibernate ORM 6.5, but a few checks have been tightened, so applications with incorrect configuration, mapping, or queries may now throw exceptions where they used to experience only warnings and malfunctions. In particular:

Some features are also now enabled by default to avoid unexpected — and arguably error-prone — behavior:

Finally, behavior was altered in some cases to comply with the JPA specification:

See the Hibernate ORM 6.6 migration guide for more details.

Flush mode configuration

Quarkus 3.13 changed the default flush mode in Hibernate ORM so that Hibernate ORM will only flush before queries if it detects relevant pending changes.

Since that default may be problematic in some applications, Quarkus 3.14.4 introduces a new configuration property, allowing applications to pick their own default. To revert to the behavior of Quarkus 3.12, use this configuration:

quarkus.hibernate-orm.flush.mode=always
Warning
 The flush mode always may cause unnecessary flushes, impacting performance negatively. It is only useful if you need behavior identical to Quarkus pre-3.13.

Micrometer

Micrometer has been upgraded from 1.12.5 to 1.13.3 in Quarkus 3.14.2. One of the changes is the use of Prometheus client v1.x, however, Quarkus will keep using the old deprecated v0.x client for longer.

This usually requires no changes from users.

However, if for some reason, you are using the old dependency in some tests: 

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

Please use the appropriate Quarkus extension instead:

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
or some features won’t work properly (for instance the /q/metrics endpoint won’t work).

The extension guarantees the use of the appropriate client and it will transparently adjust your application to use io.micrometer:micrometer-registry-prometheus-simpleclient.

MeterFilters

Beware of using bean implementations of MeterFilter to return dynamic content like:

@Singleton
public class MeterFilterProducer {

    @Inject
    RequestScopedHeader requestScopedHeader;

    @Produces
    @Singleton
    public MeterFilter addTags() {
        return new MeterFilter() {
            @Override
            public Meter.Id map(Meter.Id id) {
                if (id.getName().startsWith("something")) {
                    return id.withTag(Tag.of("my-header-tag", requestScopedHeader.getHeaderValue()));
                } else {
                    return id;
                }
            }
        };
    }
}

It is supposed the returned content to be constant and not depend on runtime. There are meter caching changes on Micrometer 1.13+ that will break metrics depending on this code.

In Quarkus, the recommended way to add tags containing data from HTTP requests is using the HttpServerMetricsTagsContributor.

SmallRye Health

Some configuration properties were incorrectly under the quarkus.health config root whereas they should have been under the quarkus.smallrye-health config root to be consistent.

This includes:

  • quarkus.health.extensions.enabled → quarkus.smallrye-health.extensions.enabled

  • quarkus.health.openapi.included → quarkus.smallrye-health.openapi.included

The old properties have been deprecated and will be removed at some point in the future.

MongoDB

The MongoDB client has been upgraded from 4.11.1 to 5.1.3.

Dev Services

Several Dev Services default images have been updated:

  • PostgreSQL from 14 to 16

  • MySQL from 8.0 to 8.4

  • MongoDB from 4.4 to 7.0

  • Elasticsearch from 8.13 to 8.15

  • OpenSearch from 2.13 to 2.16

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

For extension developers

This paragraph only concerns people developing their own Quarkus extensions.

Getting your application to compile

The extension annotation processor that is used to generate some files required for the Quarkus runtime and the configuration documentation has been redeveloped from scratch. It is a lot more flexible but comes with some new constraints:

  • You cannot mix configuration using the legacy @ConfigRoot approach (i.e. without a corresponding @ConfigMapping annotation) and the new @ConfigMapping approach in the same module. This shouldn’t be too much of a problem.

  • If you use the new @ConfigMapping approach, you don’t need to configure anything. The change should be transparent for you.

  • If you use the legacy @ConfigRoot class approach (i.e. without a corresponding @ConfigMapping annotation), you need to inform the annotation processor of it:

                <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>io.quarkus</groupId>
                            <artifactId>quarkus-extension-processor</artifactId>
                            <version>${quarkus.version}</version>
                        </path>
                    </annotationProcessorPaths>
                    <compilerArgs>
                        <arg>-AlegacyConfigRoot=true</arg>
                    </compilerArgs>
                </configuration>
            </plugin>

    The important part is the added compilerArgs -AlegacyConfigRoot=true.

    Note that this will result in a warning when compiling the test classes (given you don’t have config annotations in your test classes, the annotation processor will not be triggered and you will get a warning telling you the legacyConfigRoot parameter is unused). To alleviate this issue, it is recommended to only enable the annotation processor for the default-compile execution (which compiles the main classes):

                <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <executions>
                    <execution>
                        <id>default-compile</id>
                        <configuration>
                            <annotationProcessorPaths>
                                <path>
                                    <groupId>io.quarkus</groupId>
                                    <artifactId>quarkus-extension-processor</artifactId>
                                    <version>${quarkus.version}</version>
                                </path>
                            </annotationProcessorPaths>
                            <compilerArgs>
                                <arg>-AlegacyConfigRoot=true</arg>
                            </compilerArgs>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
    Note

    While we encourage you to move to the new @ConfigMapping interface approach (see the doc here and here), legacy @ConfigRoot classes will be supported for quite a while (they are still used in our core repository) so you don’t need to rush the migration to the new @ConfigMapping approach for your extension.

    Once we have more precise plans about when the legacy @ConfigRoot classes support will be dropped, we will make a proper announcement sufficiently early so that you can migrate your extensions comfortably.

Publishing the config documentation

The config documentation used to be generated in the root target/generated/config directory by the extension annotation processor itself.

This is not the case anymore: the extension annotation processor builds a model that is in each module, and we have a Maven plugin that assembles the model and generate the Asciidoc output.

In your typical Quarkiverse extension, you would have to apply the following changes:

  • Set the version of the quarkus-config-doc-maven-plugin in the root POM <pluginManagement> section

  • Drop the copy of the generated doc in docs/pom.xml

  • Set up the quarkus-config-doc-maven-plugin in docs/pom.xml

A typical diff would look like the following:

diff --git a/docs/pom.xml b/docs/pom.xml
index 71be73f..5022bf4 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -56,6 +56,14 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>io.quarkus</groupId>
+                <artifactId>quarkus-config-doc-maven-plugin</artifactId>
+                <extensions>true</extensions>
+                <configuration>
+                    <targetDirectory>${project.basedir}/modules/ROOT/pages/includes/</targetDirectory>
+                </configuration>
+            </plugin>
             <plugin>
                 <artifactId>maven-resources-plugin</artifactId>
                 <executions>
@@ -68,11 +76,6 @@
                         <configuration>
                             <outputDirectory>${project.basedir}/modules/ROOT/pages/includes/</outputDirectory>
                             <resources>
-                                <resource>
-                                    <directory>${project.basedir}/../target/asciidoc/generated/config/</directory>
-                                    <include>quarkus-github-app.adoc</include>
-                                    <filtering>false</filtering>
-                                </resource>
                                 <resource>
                                     <directory>${project.basedir}/templates/includes</directory>
                                     <include>attributes.adoc</include>
diff --git a/pom.xml b/pom.xml
index c87d42b..10cbacd 100644
--- a/pom.xml
+++ b/pom.xml
@@ -98,6 +98,11 @@
                     <artifactId>quarkus-maven-plugin</artifactId>
                     <version>${quarkus.version}</version>
                 </plugin>
+                <plugin>
+                    <groupId>io.quarkus</groupId>
+                    <artifactId>quarkus-config-doc-maven-plugin</artifactId>
+                    <version>${quarkus.version}</version>
+                </plugin>
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-compiler-plugin</artifactId>

Current version

Migration Guide 3.17

Next version in main

Migration Guide 3.18

Clone this wiki locally