Skip to content

Migration Guide 3.39

Jan Martiska edited this page Nov 9, 2026 · 3 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.

Quarkus Data

Packages and types ⚙️ ✅

  • Package renamed from io.quarkus.hibernate.panache to io.quarkus.data.hibernate

  • PanacheEntity was split into ManagedEntity (for Session-backed entities) and RecordEntity (for StatelessSession-backed entities)

  • Use .Reactive suffix (first) for the reactive variant

  • Use .CustomId suffix (second) if you want to define your own @Id

  • Similarly for PanacheRepository

  • PanacheQuery renamed to DataQuery

  • Most internal types renmaed to drop the Panache or Panache Next names and better readability

  • Switched from org.hibernate:hibernate-jpamodelgen annotation processor to io.quarkus:quarkus-data-processor

Sorting, ordering, paging

  • Switched to the Jakarta Data sorting, ordering and paging types

  • Grouped the paging operations in new DataQuery.pages() and DataQuery.limits()

  • Support cursors

  • Moved the optional Sort parameter from repositories operations to DataQuery

Avro (this applies to 3.39.3+ and all 3.40 releases)

Avro deserialization now validates classes

Quarkus now uses Apache Avro 1.12.2. Starting with this version, Avro checks every class against a global security validator before deserializing it. If the class is not trusted, deserialization fails with a java.lang.SecurityException.

The quarkus-avro extension comes in transitively with quarkus-apicurio-registry-avro, quarkus-confluent-registry-avro and quarkus-messaging-pulsar. It installs a validator that automatically trusts the following classes:

  • Avro-generated classes, meaning those annotated with @org.apache.avro.specific.AvroGenerated.

  • Protobuf-generated messages in applications that use quarkus-grpc or quarkus-messaging-pulsar.

  • Avro’s built-in trusted types, such as boxed primitives, String, BigDecimal and BigInteger.

Applications that only deserialize Avro-generated classes do not need to change anything.

If your application deserializes other classes through Avro, for example reflect-based POJOs, trust them with the new build-time properties:

# Trust individual classes by fully qualified name (use `$` for nested classes, e.g. org.acme.Outer$Inner)
quarkus.avro.trusted-classes=org.acme.MyClass,org.acme.OtherClass

# Trust whole packages, including their sub-packages
quarkus.avro.trusted-packages=org.acme.model

Because these are build-time properties, you need to rebuild the application after changing them. At runtime, you can still use Avro’s own org.apache.avro.SERIALIZABLE_CLASSES and org.apache.avro.SERIALIZABLE_PACKAGES system properties to trust more classes. If you use the Avro library without the quarkus-avro extension, those system properties are the only option.

Important

In @QuarkusIntegrationTest tests, the test code runs in a separate JVM that is not a Quarkus application. The quarkus.avro.trusted-* properties and the automatic trust of Avro-generated classes only apply to the application under test. They do not apply to the test JVM. If your test code deserializes Avro records itself, for example when consuming messages with KafkaCompanion, you must trust those classes in the test JVM yourself.

One way to do this is to set the system property in the Maven Failsafe configuration:

<plugin>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
        <systemPropertyVariables>
            <org.apache.avro.SERIALIZABLE_PACKAGES>org.acme.schema</org.apache.avro.SERIALIZABLE_PACKAGES>
        </systemPropertyVariables>
    </configuration>
</plugin>

The other way is to install a validator programmatically before the test consumes any messages, for example in a @BeforeAll method:

ClassSecurityValidator.setGlobal(ClassSecurityValidator.composite(
        ClassSecurityValidator.builder().add(MyRecord.class).build(),
        ClassSecurityValidator.getGlobal()));

@QuarkusTest tests are not affected because they run inside the Quarkus application.

See the Avro deserialization and class security section of the Kafka Schema Registry and Avro guide for details.

quarkus-messaging-pulsar now depends on quarkus-avro

The quarkus-messaging-pulsar extension now pulls in quarkus-avro transitively. This way, the Avro class security validator is configured for Pulsar applications.

For extension and Quarkus developers

New AvroTrustedClassBuildItem for classes deserialized through Avro

Since Avro 1.12.2, Avro rejects untrusted classes during deserialization. If your extension generates or handles classes that are deserialized through Avro, mark them as trusted. Add a dependency on io.quarkus:quarkus-avro-spi to your deployment module and produce an io.quarkus.avro.spi.AvroTrustedClassBuildItem for those classes.

@BuildStep
AvroTrustedClassBuildItem trustMyClasses() {
    return new AvroTrustedClassBuildItem(List.of("org.acme.MyGeneratedClass"));
}

The build item has no effect if the quarkus-avro extension is not present, so your extension does not need to depend on quarkus-avro.

Migration guides

Current version


LTS versions


Next version in main


Clone this wiki locally