Migration Guide 3.17

Table of Contents

• Datasources
  • No default URL for Reactive SQL clients
  • Datasources without a URL no longer contribute a health check
  • Datasource usage fails fast if datasource is deactivated or has no URL set
• Flyway
  • Flyway usage fails fast if datasource is deactivated or has no URL set
• Liquibase
  • Liquibase usage fails fast if datasource is deactivated or has no URL set
• Locales and native executables
• OpenTracing
• REST Client
  • Configuration
• Scheduler

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.

Datasources

No default URL for Reactive SQL clients

In previous versions of Quarkus, when dev services were disabled, or when running in production mode, quarkus.datasource.reactive.url/quarkus.datasource."datasource-name".reactive.url would be implicitly set to an undocumented default targeting localhost and a DB-specific port.

Starting with this version of Quarkus, when dev services are disabled, or when running in production mode, quarkus.datasource.reactive.url/quarkus.datasource."datasource-name".reactive.url no longer has a default: if the property is not set, the corresponding datasource will be deactivated, leading to the behavior described in Datasource usage fails fast if datasource is deactivated or has no URL set.

If your application needs to target localhost for one of its datasources, set quarkus.datasource.reactive.url/quarkus.datasource."datasource-name".reactive.url explicitly, for example in application.properties.

Datasources without a URL no longer contribute a health check

In previous versions of Quarkus, when dev services were disabled, or when running in production mode, and when quarkus.datasource.jdbc.url/quarkus.datasource."datasource-name".jdbc.url/quarkus.datasource.reactive.url/quarkus.datasource."datasource-name".reactive.url was not set, a health check would be contributed for the corresponding datasource regardless, resulting in unreliable health checks that would either always succeed (JDBC datasource) or (almost) always fail (reactive datasources).

Starting with this version of Quarkus, datasources without a URL will no longer contribute a health check.

If your application needs a health check for a datasource, make sure to set quarkus.datasource.jdbc.url/quarkus.datasource."datasource-name".jdbc.url/quarkus.datasource.reactive.url/quarkus.datasource."datasource-name".reactive.url explicitly.

Note	Quarkus will still attempt to detect misconfiguration on application startup, but will report it differently, potentially earlier: see Datasource usage fails fast if datasource is deactivated or has no URL set.

Datasource usage fails fast if datasource is deactivated or has no URL set

In previous versions of Quarkus, when dev services were disabled, or when running in production mode, and when the datasource was deactivated (quarkus.datasource.active=false) or had no URL set, the application would be allowed to start successfully, but could fail much later upon first access to the datasource.

Starting with this version of Quarkus, datasources that are deactivated or do not have a URL will lead to a startup failure if Quarkus can detect they are used:

• Static CDI injection points involving the datasource (@Inject DataSource ds or @Inject Pool pool) will cause application startup to fail with an explicit, actionable message.

• Dynamic retrieval of the datasource (e.g. through CDI.getBeanContainer()/Arc.instance(), or by injecting an Instance<DataSource>) will not be detected on startup, but will cause an exception to be thrown with an explicit, actionable message.

The Flyway and Liquibase extensions implement a similar behavior for their Flyway/LiquibaseFactory CDI beans.

If your application needs to inject a DataSource/Flyway/LiquibaseFactory bean for a datasource that can potentially be deactivated or have no URL, you may encounter a startup failure similar to this:

io.quarkus.arc.InactiveBeanException: Bean is not active: SYNTHETIC bean [class=io.agroal.api.AgroalDataSource, id=sqqLi56D50iCdXmOjyjPSAxbLu0]
Reason: Datasource '<default>' was deactivated automatically because its URL is not set. To activate the datasource, set configuration property 'quarkus.datasource.jdbc.url'. Refer to https://quarkus.io/guides/datasource for guidance.
To avoid this exception while keeping the bean inactive:
	- Configure all extensions consuming this bean as inactive as well, if they allow it, e.g. 'quarkus.someextension.active=false'
	- Make sure that custom code only accesses this bean if it is active
	- Inject the bean with 'Instance<io.agroal.api.AgroalDataSource>' instead of 'io.agroal.api.AgroalDataSource'
This bean is injected into:
	-io.quarkus.agroal.test.ConfigUrlMissingDefaultDatasourceStaticInjectionTest$MyBean#ds
	at io.agroal.api.AgroalDataSource_sqqLi56D50iCdXmOjyjPSAxbLu0_Synthetic_Bean.doCreate(Unknown Source)
	[...]

To avoid this failure, follow the instructions in the exception message. In particular, consider injecting the problematic bean as an InjectableInstance (for example @Inject InjectableInstance<DataSource> ds) instead. You can check whether that bean is active using .getHandle().getBean().isActive().result() on the InjectableInstance, and retrieve the bean instance using InjectableInstance#get(). See https://quarkus.io/guides/datasource#datasource-active for an example of such a setup for DataSource beans — the idea would be similar for a Flyway/LiquibaseFactory beans.

Flyway

Flyway usage fails fast if datasource is deactivated or has no URL set

Starting with this version of Quarkus, datasources that are deactivated or have no URL set will lead to a startup failure if Quarkus can detect a Flyway bean is used for that datasource.

See the similar migration guide entry for datasources for more information.

Liquibase

Liquibase usage fails fast if datasource is deactivated or has no URL set

Starting with this version of Quarkus, datasources that are deactivated or have no URL set will lead to a startup failure if Quarkus can detect a LiquibaseFactory bean is used for that datasource.

See the similar migration guide entry for datasources for more information.

Locales and native executables

When building native executables, starting with this version of Quarkus, if neither quarkus.locales nor quarkus.default-locale is set, the Quarkus applications will default to English (en_US) at run-time. Until this version, the default runtime locale when running a native executable was the build system locale.

Similarly, if quarkus.locales is set but quarkus.default-locale is not set, then Quarkus will include in the native executable only the locales from quarkus.locales and default to English at run-time. That means that no matter the quarkus.locales configuration, the en_US locale will always get embedded in the native executable.

This is to ensure that the default locale is consistent across all Quarkus native executables, regardless of the build system locale.

Furthermore, starting with this version and in combination with GraalVM for JDK 24 and later (which is not yet released), native executables will be able to pick up the default locale at runtime from the system properties user.language and user.country and override the quarkus.default-locale if set. If the locales picked up at runtime are not present in the quarkus.locales configuration, the en_US locale will be used.

OpenTracing

OpenTracing has been completely removed from Quarkus, including OpenTracing dependencies from the Application BOM. If you are still using Opentracing, please move to OpenTelemetry by following the guide Migrate from OpenTracing to OpenTelemetry tracing.

REST Client

Configuration

The REST Client Configuration became more strict to reduce the number of lookups and combinations required to retrieve the configuration:

• The MicroProfile Rest Client config style [Simple Class Name]/mp-rest does not work anymore. This style is not specified by the specification. The FQCN/mp-rest style continues to as expected (as specified by MicroProfile Rest Client).

• Only REST Clients discovered by Quarkus are loaded by the RestClientsConfig and RestClientsBuildTimeConfig.

• The RestClientsConfig#clients and RestClientsBuildTimeConfig#client map always uses the FQCN of the REST Client interface. Before, it would use all the keys found, even if related to the same REST Client duplicating (or more) entries.

• Removed legacy configuration names quarkus.rest.client.max-redirects and quarkus.rest.client.multipart-post-encoder-mode

Scheduler

There is a behavior change for methods on io.quarkus.scheduler.Scheduler if the scheduler wasn’t started:

• Almost all methods will now throw UnsupportedOperationException.

• Newly added method Scheduler#isStarted() can be used to verify this state.

• This change affects scheduler instances coming from both Quarkus extensions (scheduler and quartz).