Configuring data sources in your Quarkus applications
Abstract
Providing feedback on Red Hat documentation Copy linkLink copied to clipboard!
We appreciate your feedback on our technical content and encourage you to tell us what you think. If you’d like to add comments, provide insights, correct a typo, or even ask a question, you can do so directly in the documentation.
You must have a Red Hat account and be logged in to the customer portal.
To submit documentation feedback from the customer portal, do the following:
- Select the Multi-page HTML format.
- Click the Feedback button at the top-right of the document.
- Highlight the section of text where you want to provide feedback.
- Click the Add Feedback dialog next to your highlighted text.
- Enter your feedback in the text box on the right of the page and then click Submit.
We automatically create a tracking issue each time you submit feedback. Open the link that is displayed after you click Submit and start watching the issue or add more comments.
Thank you for the valuable feedback.
Making open source more inclusive Copy linkLink copied to clipboard!
Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.
Chapter 1. Introduction to using data sources with Quarkus Copy linkLink copied to clipboard!
When you want to add persistent data storage to your application, you must connect your application to a relational database. To achieve this, you use a data source that you connect to your application using a database driver. You can connect your Quarkus application to one or multiple data sources. You can use the data source management functionalities integrated into Quarkus to:
- configure your application to use one or multiple data sources
- obtain references to data sources in your code
- view and set pool tuning configuration properties
In Quarkus applications, you can use two types of database drivers to connect your application to a relational database. You can use multiple data sources of both types in one application simultaneously:
- JDBC drivers
- that use the standard JDBC API that provides database connectivity for Java-based application. Quarkus JDBC drivers manage database connections using Agroal, a fast, light-weight, and highly scalable database connection pool implementation that is integrated with other features of Quarkus, including security, transaction management and health checks.
- Reactive drivers
- that are based on the data source driver implementation in Eclipse Vert.x. Eclipse Vert.x reactive data source drivers provide the non-blocking and reactive network-related features of Quarkus and are suitable for applications that are designed to be highly scalable and event-driven.
You can configure both types of data source drivers using a set of unified and flexible configuration options that Quarkus provides.
1.1. Setting the db-kind property for a data source Copy linkLink copied to clipboard!
When you set the db-kind property in the configuration file of your application to match the type of your data source that you want to use, Quarkus automatically resolves the appropriate type of database driver. The following procedure demonstrates how you can set the db-kind property for a data source.
Prerequisites
- You have a Quarkus Maven project.
Procedure
- Navigate to your Quarkus project directory.
In the
src/main/resources/application.propertiesfile, set the value of thedb-kindproperty to match the type of the data source that you want to use. The following example usespostgresqlas the data source type:quarkus.datasource.db-kind=postgresql
quarkus.datasource.db-kind=postgresqlCopy to Clipboard Copied! Toggle word wrap Toggle overflow
1.2. Setting database credentials Copy linkLink copied to clipboard!
You can define credentials that your application uses to access your database. Defining access credentials for your database is optional. You can skip this procedure when configuring a data source for your application.
Prerequisites
- You have a Quarkus Maven project.
-
You have set the
db-kindproperty for your data source. - Your Quarkus application is in JVM mode. This prerequisite applies when you use a JDBC driver that Quarkus does not support in native mode.
Procedure
- Navigate to your Quarkus project directory.
In the
src/main/resources/application.propertiesfile, set the value of thequarkus.datasource.usernameproperty to match the username that your application uses to access the database:quarkus.datasource.username=<username>
quarkus.datasource.username=<username>Copy to Clipboard Copied! Toggle word wrap Toggle overflow In the
src/main/resources/application.propertiesfile, set the value of thequarkus.datasource.passwordproperty to match the password that your application uses to access the database:quarkus.datasource.password=<password>
quarkus.datasource.password=<password>Copy to Clipboard Copied! Toggle word wrap Toggle overflow
1.3. Quarkus driver extensions for built-in databases Copy linkLink copied to clipboard!
The following table provides an overview of Quarkus built-in databases and the extensions that you can use to connect your application to a relational database:
| Database built-in | db-kind | Agroal extension | Reactive extension |
|---|---|---|---|
| DB2 |
|
|
|
| Derby |
|
| N/A |
| H2 |
|
| N/A |
| MariaDB |
|
|
|
| Microsoft SQL Server |
|
| N/A |
| MySQL |
|
|
|
| PostgreSQL |
|
|
|
You can configure H2 and Derby databases to run in embedded mode. The H2 and Derby driver extensions do not support compiling the embedded database engine into native executables.
This table includes supported and community artifacts. For a list of supported Maven artifacts, see the Red Hat build of Quarkus Component Details page.
When you use one of the built-in database kinds the JDBC driver resolves automatically to the following values:
| Database | JDBC driver | XA driver |
|---|---|---|
| DB2 |
|
|
| Derby |
|
|
| H2 |
|
|
| MariaDB |
|
|
| Microsoft SQL Server |
|
|
| MySQL |
|
|
| PostgreSQL |
|
|
You can configure H2 and Derby databases to run in embedded mode. The H2 and Derby driver extensions do not support compiling the embedded database engine into native executables.
Chapter 2. JDBC data source configuration Copy linkLink copied to clipboard!
JDBC is the database connection API most commonly used in Java-based applications. You can use a JDBC data source driver to connect your application to a relational database.
To configure a JDBC data source, you must
-
add the
quarkus-agroalextension to your application -
add a
db-kindextension to your application - specify the JDBC URL that your application uses to access the data source
The following example shows how you can connect a postgresql data source to your application and specify the access credentials and the JDBC URL for the data source. For more information on how to specify the JDBC URL see Setting the JDBC URL of your data source.
Example of JDBC data source configuration
2.1. Installing Quarkus extensions for JDBC data sources Copy linkLink copied to clipboard!
You must install the quarkus-agroal extension and a Quarkus JDBC database driver extension to configure a JDBC data source. The JDBC database driver that you add must match the type of JDBC database that you want to use.
The following procedure demonstrates how to install Quarkus extensions for JDBC data sources.
Prerequisites
- You have a Quarkus Maven project.
-
You have set the
db-kindproperty for your data source.
Procedure
- Navigate to your Quarkus project directory.
Add the
quarkus-agroalextension to your project:./mvnw quarkus:add-extension -Dextensions="agroal"
./mvnw quarkus:add-extension -Dextensions="agroal"Copy to Clipboard Copied! Toggle word wrap Toggle overflow Add the Quarkus extension for the appropriate type of relational database driver to your application:
./mvnw quarkus:add-extension -Dextensions="<extension>"
./mvnw quarkus:add-extension -Dextensions="<extension>"Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to add a PostgreSQL database driver extension, use:
./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"Copy to Clipboard Copied! Toggle word wrap Toggle overflow
If you are using Hibernate ORM, you do not need to add the Agroal extension dependency explicitly. Agroal is a transitive dependency of the Hibernate ORM extension. You must use a JDBC data source driver with Hibernate ORM.
2.2. Setting the JDBC URL of your data source Copy linkLink copied to clipboard!
You must set the JDBC URL to complete the configuration of your JDBC data source. The following procedure demonstrates how to set the JDBC URL.
Prerequisites
- You have a Quarkus Maven project.
- You have added the corresponding data source driver to your application.
-
You have set the
db-kindproperty for your data source.
Procedure
- Navigate to your Quarkus project directory.
-
Open the
src/main/resources/application.propertiesfile. Set the value of the
quarkus.datasource.jdbc.urlproperty to match the JDBC URL for your data source:quarkus.datasource.jdbc.url=<JDBC_URL>
quarkus.datasource.jdbc.url=<JDBC_URL>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to set the JDBC URL of a PostgreSQL data source, use:
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_testCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.3. Obtaining a JDBC data source with Hibernate ORM Copy linkLink copied to clipboard!
If you are using Hibernate ORM, your application automatically recognizes and connects to an available JDBC data source. To access the data source in your application code, you can obtain it as a CDI bean.
Prerequisites
- You have a Quarkus Maven project.
- You have installed Hibernate ORM.
Procedure
To access the data source in your application code, add the
@Injectannotation to thedataSourceproperty:import javax.sql.DataSource; @Inject DataSource dataSource;
import javax.sql.DataSource; @Inject DataSource dataSource;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4. Disabling a JDBC data source in a simultaneous configuration Copy linkLink copied to clipboard!
You can simultaneously configure a JDBC driver extension and a reactive driver extension for the same data source in your application. You can disable the JDBC data source driver in a simultaneous configuration, thus forcing your application to use the reactive data source driver.
Prerequisites
- You have a Quarkus Maven project.
- You have a JDBC data source driver and a reactive data source driver configured simultaneously in your application.
Procedure
- Navigate to your Quarkus project directory.
-
Open the
src/main/resources/application.propertiesfile. Set the
quarkus.datasource.jdbcproperty tofalseto disable the JDBC data source:quarkus.datasource.jdbc=false
quarkus.datasource.jdbc=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.5. Configuring JDBC drivers with no built-in driver extension Copy linkLink copied to clipboard!
You can use JDBC drivers and databases that do not have built-in driver extensions. The following procedure demonstrates how to configure a JDBC driver with no built-in extension.
You can use any JDBC driver while using your Quarkus application in JVM mode. The non-included JDBC drivers may not function properly when you compile your Quarkus as a native executable.
Prerequisites
- You have a Quarkus Maven project.
- Your Quarkus application is in JVM mode.
-
You add the data source driver that you want to use as a dependency in the
pom.xmlfile of your project.
Procedure
- Navigate to your Quarkus project directory.
-
Open the
src/main/resources/application.propertiesfile. Set the value of the
db-kindproperty toother:quarkus.datasource.db-kind=other
quarkus.datasource.db-kind=otherCopy to Clipboard Copied! Toggle word wrap Toggle overflow Set the value of the
quarkus.datasource.jdbc.driverproperty to match the type of driver extension that you want to use:quarkus.datasource.jdbc.driver=<driver>
quarkus.datasource.jdbc.driver=<driver>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Set the value of the
quarkus.datasource.jdbc.urlproperty to match the JDBC URL for your data source:quarkus.datasource.jdbc.url=<JDBC_URL>
quarkus.datasource.jdbc.url=<JDBC_URL>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, Quarkus does not provide a built-in driver extension for the OpenTracing driver. Ensure that you add the
opentracing-jdbcartifact to yourpom.xmlfile, and set the following properties in yourapplication.propertiesfile to configure the OpenTracing driver:quarkus.datasource.db-kind=postgresql quarkus.datasource.jdbc.url=jdbc:tracing:postgresql://localhost:5432/mydatabase quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialect
quarkus.datasource.db-kind=postgresql quarkus.datasource.jdbc.url=jdbc:tracing:postgresql://localhost:5432/mydatabase quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialectCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.6. Configuring multiple JDBC data sources Copy linkLink copied to clipboard!
You can configure multiple JDBC data sources for your Quarkus application with Agroal.
When you use the Hibernate ORM extension, you can add multiple persistent data storage units to your application. For each persistence unit, you can point to the data source of your choice.
Prerequisites
- You have a Quarkus Maven project.
- You have multiple JDBC data sources.
Procedure
- Navigate to your Quarkus project directory.
In the
src/main/resources/application.propertiesfile, set the following properties for each of your data sources:The following example shows the complete configuration for 3 JDBC data sources:
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 1
- The type of the data source that you want to use.
- 2
- The username for the data source.
- 3
- The JDBC connection URL of the data source.
- 4
- The minimum number of connections that are maintained in the connection pool of the data source.
- 5
- The maximum number of connections that are maintained in the connection pool of the data source.
- 6
- If you choose
usersas the name of the data source, the fully qualified reference of your data source isquarkus.datasource.users
Inject multiple data sources into by adding the
@Injectannotation to each one of the class properties. When you configure multiple data sources for your application, ensure that you add theio.quarkus.agroal.DataSourcequalifier with the name of the data source as the value to eachDataSourceclass:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 3. Reactive data source configuration Copy linkLink copied to clipboard!
You can use a reactive data source driver to connect your application to a relational database.
3.1. Setting the reactive data source connection URL Copy linkLink copied to clipboard!
You must configure the connection URL for the reactive data source to complete configuration of your data source.
Prerequisites
- You have a Quarkus Maven project.
- You have added a reactive data source driver to your application.
Procedure
- Navigate to your Quarkus project directory.
In the
src/main/resources/application.propertiesfile, set the value of thequarkus.datasource.reactive.urlproperty to match the connection URL of your reactive data source:quarkus.datasource.reactive.url=<datasource_URL>
quarkus.datasource.reactive.url=<datasource_URL>Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to set the reactive data source connection URL for the PostgreSQL data source:
quarkus.datasource.reactive.url=postgresql:///your_database
quarkus.datasource.reactive.url=postgresql:///your_databaseCopy to Clipboard Copied! Toggle word wrap Toggle overflow Optionally, you can set the maximum number of connections in the connection pool of your data source to improve the performance of your application:
quarkus.datasource.reactive.max-size=20
quarkus.datasource.reactive.max-size=20Copy to Clipboard Copied! Toggle word wrap Toggle overflow For example, to add a
postgresqldata source with a reactive data source driver:Copy to Clipboard Copied! Toggle word wrap Toggle overflow
3.2. Disabling a reactive data source in a simultaneous configuration Copy linkLink copied to clipboard!
You can simultaneously configure a reactive driver extension and a JDBC driver extension for the same data source in your application. You can disable the reactive data source driver in a simultaneous configuration, thus forcing your application to use the JDBC data source driver.
Prerequisites
- You have a Quarkus Maven project.
- You have a JDBC data source driver and a reactive data source driver configured simultaneously in your application.
Procedure
- Navigate to your Quarkus project directory.
-
Open the
src/main/resources/application.propertiesfile. Set the
quarkus.datasource.reactiveproperty tofalseto disable the reactive data source:quarkus.datasource.reactive=false
quarkus.datasource.reactive=falseCopy to Clipboard Copied! Toggle word wrap Toggle overflow
Chapter 4. Data source management Copy linkLink copied to clipboard!
You can enable additional features through application properties to manage data sources.
4.1. Data source health check Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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.
4.3. Narayana transaction manager integration Copy linkLink copied to clipboard!
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 Copy linkLink copied to clipboard!
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:
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
Appendix A. JDBC database connection URLs for databases with production and development support Copy linkLink copied to clipboard!
You can use a JDBC database connection URL to connect to a relational database. Each database has its own format of the database URL that contains information about the database itself and other configuration properties.
The following examples show you JDBC database connection URLs for databases that have been tested with Red Hat build of Quarkus. For more information about supported databases and versions, see the Red Hat build of Quarkus Supported Configurations page.
A.1. PostgreSQL database URL example Copy linkLink copied to clipboard!
PostgreSQL runs only as a server. You must specify connection details or use the default values.
Configuration options
jdbc:postgresql:[//][host][:port][/database][?key=value…]
jdbc:postgresql:[//][host][:port][/database][?key=value…]
Example
jdbc:postgresql://localhost/test
jdbc:postgresql://localhost/test
A.2. MariaDB database URL example Copy linkLink copied to clipboard!
MariaDB only runs as a server. You must specify connection details or use the default values.
Configuration options
jdbc:mariadb:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
jdbc:mariadb:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
Example
jdbc:mariadb://localhost:3306/test
jdbc:mariadb://localhost:3306/test
A.3. MySQL database URL example Copy linkLink copied to clipboard!
MySQL runs only as a server. You must specify connection details or use the default values.
Configuration options
jdbc:mysql:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
jdbc:mysql:[replication:|failover:|sequential:|aurora:]//<hostDescription>[,<hostDescription>…]/[database][?<key1>=<value1>[&<key2>=<value2>]] hostDescription:: <host>[:<portnumber>] or address=(host=<host>)[(port=<portnumber>)][(type=(master|slave))]
Example
jdbc:mysql://localhost:3306/test
jdbc:mysql://localhost:3306/test
A.4. Microsoft SQL Server database URL example Copy linkLink copied to clipboard!
Microsoft SQL Server uses default system values unless you specify different values. The Microsoft SQL Server JDBC drivers function the same way as other drivers. The connection URL should be in the following format:
Configuration options
jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]
jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]
Example
jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks
jdbc:sqlserver://localhost:1433;databaseName=AdventureWorks
Appendix B. JDBC database connection URLs for databases with development support Copy linkLink copied to clipboard!
You can use a JDBC database connection URL to connect to a relational database. Each database has its own format of the database URL that contains information about the database itself and other configuration properties.
The following examples show you JDBC database connection URLs for databases with development support. For more information about development support, see the Development Support Scope of Coverage page.
B.1. Derby database URL example Copy linkLink copied to clipboard!
Derby is an embedded database that can run as a server, based on a file, or live in memory.
Configuration options
jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]
jdbc:derby:[//serverName[:portNumber]/][memory:]databaseName[;property=value[;property=value]]
Example
jdbc:derby://localhost:1527/myDB, jdbc:derby:memory:myDB;create=true
jdbc:derby://localhost:1527/myDB, jdbc:derby:memory:myDB;create=true
B.2. H2 database URL example Copy linkLink copied to clipboard!
H2 is an embedded database that can run as a server, based on a file, or live completely in memory.
Configuration options
jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value…]
jdbc:h2:{ {.|mem:}[name] | [file:]fileName | {tcp|ssl}:[//]server[:port][,server2[:port]]/name }[;key=value…]
Example
jdbc:h2:tcp://localhost/~/test, jdbc:h2:mem:myDB
jdbc:h2:tcp://localhost/~/test, jdbc:h2:mem:myDB
Revised on 2021-06-24 09:07:31 UTC