Chapter 4. Data source management with Quarkus

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 quarkus.datasource.health.enabled property.

When you use either the quarkus-smallrye-metrics or the quarkus-micrometer extension, metrics emitted by the quarkus-agroal extension are exposed on the metrics endpoint /q/metrics.

To enable metrics for all data sources, you can set the quarkus.datasource.jdbc.enable-metrics property to true. To disable metrics for all data sources, set quarkus.datasource.jdbc.enable-metrics property to false.

When you have data source metrics enabled (quarkus.datasource.jdbc.enable-metrics=true), you can disable metrics for a specific data source by setting quarkus.datasource.<datasource_name>.jdbc.enable-metrics property for a named data source to false.

When you have data source metrics disabled (quarkus.datasource.jdbc.enable-metrics=false), you can enable metrics for a specific datasource by setting quarkus.datasource.<datasource_name>.jdbc.enable-metrics property for a named data source to true.

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.

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.

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:

package my.app.integrationtests.db;

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

@QuarkusTestResource(H2DatabaseTestResource.class)
public class TestResources {
}

package my.app.integrationtests.db;

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

@QuarkusTestResource(H2DatabaseTestResource.class)
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:

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:test

quarkus.datasource.db-kind=h2
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:test