Migration Guide 3.12

Table of Contents

• Hibernate ORM
  • Database version now gets verified on startup even if relying on defaults
• Spring compatibility layer aligned with Spring Boot 3
  • Key Changes in Spring Data JPA latest version
  • Refactoring of Spring Data REST extension:
• OpenTelemetry
  • Breaking Changes
• Mailer with START TLS configuration

Hibernate ORM

Database version now gets verified on startup even if relying on defaults

The Hibernate ORM extension for Quarkus now verifies that the database version it connects to at runtime is at least as high as the one configured at build time, even when that configuration is not explicit (i.e. when relying on the defaults that target Quarkus' minimum supported DB versions).

This change was made to make application developers aware they use a version of the database that is no longer considered as supported by Hibernate ORM or Quarkus: in that case, Quarkus will refuse to start with an exception.

This change should only affect applications relying on older database versions:

• DB2 older than 10.5

• Derby older than 10.15.2

• Oracle Database older than 19.0

• MariaDB older than 10.6

• Microsoft SQL Server older than 13 (2016)

• MySQL older than 8.0

• PostgreSQL older than 12.0

See here for details.

If the database cannot be upgraded to a supported version, it is still possible to use it, although some features might not work. To continue using an older, unsupported version of a database:

• Set the db-version explicitly

• If necessary, set the dialect explicitly. In some cases, very old databases versions require using a legacy dialect found in the hibernate-community-dialects Maven artifact. See here for more information.

Spring compatibility layer aligned with Spring Boot 3

Key Changes in Spring Data JPA latest version

Introduction of New Interfaces: - With spring-data-jpa 3.x, two new interfaces, ListCrudRepository and ListPagingAndSortingRepository, were introduced. These interfaces return List<T> types, unlike the existing PagingAndSortingRepository and CrudRepository, which return Iterable<T>. - The class hierarchy has been modified: PagingAndSortingRepository no longer extends CrudRepository. Instead, JpaRepository now extends both CrudRepository and PagingAndSortingRepository.

Refactoring of Spring Data REST extension:

• To accommodate these changes, the extension’s hierarchy was restructured. Rather than maintaining different implementors, a single implementor now checks the repository type and implements the corresponding methods.

• All logic is consolidated in the RepositoryMethodsImplementor, which implements all repository methods based on the repository type.

• The SpringDataRestProcessor has been updated to include the new interfaces and now performs registration in a unified method (registerRepositories) instead of using two separate methods.

• Unification of PropertiesProvider Classes: these classes have been unified to incorporate the new methods from the List***Repository interfaces.

• Updates to EntityClassHelper: the EntityClassHelper has been relocated and now includes new methods used by RepositoryMethodsImplementor to detect the repository type for implementation.

• Modifications to Tests: the Paged*Test no longer checks methods inherited from CrudRepos. A new test case, CrudAndPagedResourceTest, has been added for a repository extending both Crud and Paged repositories.

Note: The new List** methods are not specifically exposed via REST, as this is consistent with Spring’s behavior.

OpenTelemetry

Breaking Changes

Legacy configuration properties that use the quarkus.opentelemetry.* namespace have been removed after almost one year of transition period.

Please remember the changes done for Quarkus 3.0:

All configurations have been updated from quarkus.opentelemetry. → quarkus.otel. to follow the OpenTelemetry Java autoconfigure conventions.

The sample configuration change requires additional work: quarkus.opentelemetry.tracer.sampler → quarkus.otel.traces.sampler.

If the sampler is parent based, there is no need to set, the now dropped property, quarkus.opentelemetry.tracer.sampler.parent-based.

The values you need to set on quarkus.opentelemetry.tracer.sampler are now:

Old Sampler config value	New Sampler config value	New Sampler config value (Parent based)
on	always_on	parentbased_always_on
off	always_off	parentbased_always_off
ratio	traceidratio	parentbased_traceidratio

Mailer with START TLS configuration

In previous versions, configuring the mailer with START_TLS was ambiguous. In 3.12+, the configuration has been extended to avoid any ambiguity whether a TLS connection must be established to connect to the SMTP server or is later upgraded to TLS using the START_TLS command.

You now need to explicitly configure quarkus.mailer.tls to false to make sure it does not establish a TLS connection to the SMTP server:

quarkus.mailer.from=...
quarkus.mailer.host=...
quarkus.mailer.port=...
qauarkus.mailer.mock=false

quarkus.mailer.tls=false # Required to use START_TLS
quarkus.mailer.start-tls=REQUIRED 

For named mailer, use quarkus.mailer.<name>.tls=false.