Chapter 1. Introduction to using data sources with Quarkus
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
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
Additional resources
1.2. Setting database credentials
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>
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>
Additional resources
1.3. Quarkus driver extensions for built-in databases
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:
Table 1.1. Driver extensions for Quarkus built-in databases
| 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:
Table 1.2. JDBC and XA drivers for Quarkus built-in databases
| 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.
