How to upgrade to Quarkus 3

This article discusses how to upgrade your existing Quarkus 2.x applications to Quarkus 3.x using the Quarkus CLI tool. We will learn at first which is the impact of the upgrade on Quarkus 2 application. Then, we will show how to perform the upgrade with just a single command line!

What is new in Quarkus 3 ?

There are several highlights in the new major version of Quarkus. A detailed wiki of the changes available in Quarkus 3 is available in this GitHub page: https://github.com/quarkusio/quarkus/wiki/Migration-Guide-3.0 . Here we will summarize the hot picks in the new version of Quarkus

A brand new Dev UI

With Quarkus 3.0, the Dev UI undergoes a significant transformation. It becomes more extensible, user-friendly, and boasts a sleek new look and feel. This new Dev UI is avaiable at /q/dev-ui and it is now the default choice for developers, offering a seamless development environment. However, it’s important to note that not all extensions have migrated to the new Dev UI. As a result, the old version can still be accessed at /q/dev-v1.

Jakarta EE 10 Integration

Quarkus 2 was built on Jakarta EE 8, but Quarkus 3.0 takes a leap forward by embracing Jakarta EE 10. The most noticeable change is the shift from javax.* packages to jakarta.*. This transition necessitates adjustments to source code and dependencies, including transitive dependencies relying on the old javax.* packages.

It’s essential to emphasize that only the javax.* packages from Jakarta EE have undergone this transformation, while those from the JDK remain unchanged.

Eclipse MicroProfile 6

Eclipse MicroProfile 6.0 aligns itself with the Jakarta EE 10 Core Profile, making the transition seamless for developers. An exciting change is the replacement of MicroProfile OpenTracing with MicroProfile Telemetry, enhancing observability and telemetry capabilities in your applications.

Hibernate ORM 6.2

One of the most significant enhancements in Quarkus 3 is the upgrade of Hibernate ORM from version 5 to version 6.2. This marks a major milestone for Hibernate ORM, introducing a slew of changes, some of which are breaking. Developers are encouraged to review the Hibernate ORM 5 to 6 migration guide to understand these changes from a Quarkus user’s perspective.

Hibernate ORM 6 introduces various improvements and optimizations. To delve deeper into these changes, refer to the Hibernate ORM release announcements for versions 6.0, 6.1, and 6.2.

Upgrading to Quarkus 3

The simplest option to upgrade your applications to Quarkus 3 is to use the Quarkus CLI Tool. If you are new to this tool, we recommend checking this article: Quarkus CLI Introduction.

When the Quarkus CLI is available, all you need to complete the upgrade is running the following command:

quarkus update --stream=3.0

Behind the hoods, the quarkus update command will execute a set of OpenRewrite transformation rules. Most of the rules are defined in the Quarkus Update Recipes project.

Another option to complete the upgrade is executing the Quarkus Maven plugin directly. For example:

./mvnw io.quarkus.platform:quarkus-maven-plugin:3.0.3.Final:update -N -Dstream=3.0

The outcome

We will apply the upgrade on one of our quickstarts: Getting started with Quarkus and Hibernate

Upon successful completion of the `quarkus update command, let’s check our project resources:

import jakarta.inject.Inject;
import jakarta.persistence.EntityManager;
import jakarta.transaction.Transactional;
import jakarta.ws.rs.*;
import jakarta.ws.rs.core.Response;
@Path("/customer")
@Produces("application/json")
@Consumes("application/json")
public class ExampleResource {
 . . . .
}

As you can see, the javax packages have been moved to jakarta, to be Jakarta EE 10 compliant.

Besides, the pom.xml now references Quarkus 3.0 coordinates:

    <properties>
        <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
        <quarkus.platform.group-id>io.quarkus</quarkus.platform.group-id>
        <quarkus.platform.version>3.0.4.Final</quarkus.platform.version>
        <surefire-plugin.version>3.0.0-M7</surefire-plugin.version>
        <compiler-plugin.version>3.8.0</compiler-plugin.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <maven.compiler.release>11</maven.compiler.release> 
    </properties>

Please note that you can further upgrade your Quarkus application by setting a newer minor version. For example, to upgrade to version 3.3 you can run the quarkus update command as follows:

quarkus update --stream=3.3

Troubleshooting notes

Please note, the current version of the update command is not able to determine the Java version of the current project. Therefore, make sure you include the Java target release as property in your project.

<maven.compiler.release>11</maven.compiler.release>

Conclusion

This article discussed the major enhancements introduced in Quarkus 3 and how you can perform a smooth and fast migration of your Quarkus projects from version 2.x to the latest 3.x version.