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