Chapter 4. Data source management

You can enable additional features through application properties to manage data sources.

4.1. Data source health check

External systems (like Kubernetes) perform health checks on your data sources to determine if your application is able to respond to requests.

If you are using the quarkus-smallrye-health extension, the quarkus-agroal and reactive client extensions automatically add a readiness health check to validate the data source.

To view information about the data source validation status, access the /health/ready endpoint of your application. If you have multiple data sources, the application checks all data sources and their statuses will be listed as DOWN on the endpoint if there is a data source validation failure.

You can disable this behavior using the property.

4.2. Data source metrics

When you use the quarkus-smallrye-metrics extension, the quarkus-agroal extension can expose data source metrics on the /metrics endpoint. You can set the quarkus.datasource.metrics.enabled property to true to enable this behavior.

To disable metrics for a particular data source, you can set the quarkus.datasource.jdbc.enable-metrics property to false or the quarkus.datasource.<datasource_name>.jdbc.enable-metrics property for a named data source to false. This disables metric collection and exposes the data source in the /metrics endpoint.

To enable metrics for a particular data source, you can set the quarkus.datasource.jdbc.enable-metrics property to true or quarkus.datasource.<datasource_name>.jdbc.enable-metrics property for a named data source to true. This enables collection of metrics even if the quarkus-smallrye-metrics extension is not enabled.

You can use this feature to access the collected metrics programmatically. The collected metrics are available after calling the dataSource.getMetrics() method on an injected AgroalDataSource instance. If collection of metrics is disabled for the data source, all values are zero.

4.3. Narayana transaction manager integration

Narayana transaction manager integration is automatically added when the quarkus-narayana-jta extension is available.

You can override this by setting the quarkus.datasource.jdbc.transactions configuration property.

4.4. Test with in-memory databases

Use the database you intend to use in production, container technologies made it simple to achieve. It is possible to run integration tests using the JVM powered databases as well. H2 and Derby databases are commonly used in embedded mode to run integration tests.

The embedded engine will function properly in JVM mode but is unable to compile into a native executable. Quarkus does not support embedding the entire database engine into a native executable.

If you want to run integration tests in both JVM and/or native executables, you can add either @QuarkusTestResource(H2DatabaseTestResource.class) or @QuarkusTestResource(DerbyDatabaseTestResource.class) on any class in your integration tests. The test suite can now start and stop the embedded database as a separate process as necessary to run your tests.

@QuarkusTestResource(H2DatabaseTestResource.class) and @QuarkusTestResource(DerbyDatabaseTestResource.class) are provided by the artifacts having Maven coordinates io.quarkus:quarkus-test-h2 and io.quarkus:quarkus-test-derby, respectively for H2 and Derby.

The following example demonstrates how to use the helper for H2 databases:


import io.quarkus.test.common.QuarkusTestResource;
import io.quarkus.test.h2.H2DatabaseTestResource;

public class TestResources {

This allows you to test your application even when it is compiled into a native executable, while the database will run in the JVM as usual.

Connect to it using: