Chapter 2. JDBC data source configuration

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-agroal extension to your application
  • add a db-kind extension 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

quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=<your_username>
quarkus.datasource.password=<your_password>

quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
quarkus.datasource.jdbc.max-size=16

2.1. Installing Quarkus extensions for JDBC data sources

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-kind property for your data source.

Procedure

  1. Navigate to your Quarkus project directory.

  2. Add the quarkus-agroal extension to your project: 

    ./mvnw quarkus:add-extension -Dextensions="agroal"

  3. Add the Quarkus extension for the appropriate type of relational database driver to your application: 

    ./mvnw quarkus:add-extension -Dextensions="<extension>"

    For example, to add a PostgreSQL database driver extension, use: 

    ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
Note

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.

Additional resources

2.2. Setting the JDBC URL of your data source

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-kind property for your data source.

Procedure

  1. Navigate to your Quarkus project directory.
  2. Open the src/main/resources/application.properties file.

  3. Set the value of the quarkus.datasource.jdbc.url property to match the JDBC URL for your data source: 

    quarkus.datasource.jdbc.url=<JDBC_URL>

    For example, to set the JDBC URL of a PostgreSQL data source, use: 

    quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test

Additional resources

2.3. Obtaining a JDBC data source with Hibernate ORM

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 @Inject annotation to the dataSource property: 

    import javax.sql.DataSource;

@Inject DataSource dataSource;

2.4. Disabling a JDBC data source in a simultaneous configuration

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

  1. Navigate to your Quarkus project directory.
  2. Open the src/main/resources/application.properties file.

  3. Set the quarkus.datasource.jdbc property to false to disable the JDBC data source: 

    quarkus.datasource.jdbc=false

2.5. Configuring JDBC drivers with no built-in driver extension

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.

Note

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.xml file of your project.

Procedure

  1. Navigate to your Quarkus project directory.
  2. Open the src/main/resources/application.properties file.

  3. Set the value of the db-kind property to other: 

    quarkus.datasource.db-kind=other

  4. Set the value of the quarkus.datasource.jdbc.driver property to match the type of driver extension that you want to use: 

    quarkus.datasource.jdbc.driver=<driver>

  5. Set the value of the quarkus.datasource.jdbc.url property to match the JDBC URL for your data source: 

    quarkus.datasource.jdbc.url=<JDBC_URL>

    For example, Quarkus does not provide a built-in driver extension for the OpenTracing driver. Ensure that you add the opentracing-jdbc artifact to your pom.xml file, and set the following properties in your application.properties file 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

2.6. Configuring multiple JDBC data sources

You can configure multiple JDBC data sources for your Quarkus application with Agroal.

Note

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

  1. Navigate to your Quarkus project directory.

  2. In the src/main/resources/application.properties file, set the following properties for each of your data sources:

    The following example shows the complete configuration for 3 JDBC data sources: 

    quarkus.datasource.db-kind=h2 1
quarkus.datasource.username=username-default 2
quarkus.datasource.jdbc.url=jdbc:h2:tcp://localhost/mem:default 3
quarkus.datasource.jdbc.min-size=3 4
quarkus.datasource.jdbc.max-size=13 5

quarkus.datasource.users.db-kind=h2 6
quarkus.datasource.users.username=username1
quarkus.datasource.users.jdbc.url=jdbc:h2:tcp://localhost/mem:users
quarkus.datasource.users.jdbc.min-size=1
quarkus.datasource.users.jdbc.max-size=11

quarkus.datasource.inventory.db-kind=h2
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.jdbc.url=jdbc:h2:tcp://localhost/mem:inventory
quarkus.datasource.inventory.jdbc.min-size=2
quarkus.datasource.inventory.jdbc.max-size=12
    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 users as the name of the data source, the fully qualified reference of your data source is quarkus.datasource.users

  3. Inject multiple data sources into by adding the @Inject annotation to each one of the class properties. When you configure multiple data sources for your application, ensure that you add the io.quarkus.agroal.DataSource qualifier with the name of the data source as the value to each DataSource class: 

    import javax.inject.Inject;
import io.agroal.api.AgroalDataSource;
import io.quarkus.agroal.DataSource;

@Inject
AgroalDataSource defaultDataSource;

@Inject
@DataSource("users")
AgroalDataSource usersDataSource;

@Inject
@DataSource("inventory")
AgroalDataSource inventoryDataSource;

Additional resources