Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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
Copy to Clipboard Toggle word wrap

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"
    Copy to Clipboard Toggle word wrap

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

    ./mvnw quarkus:add-extension -Dextensions="<extension>"
    Copy to Clipboard Toggle word wrap

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

    ./mvnw quarkus:add-extension -Dextensions="jdbc-postgresql"
    Copy to Clipboard Toggle word wrap
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.

2.2. Setting the JDBC URL of your data source
Copy link

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>
    Copy to Clipboard Toggle word wrap

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

    quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/hibernate_orm_test
    Copy to Clipboard Toggle word wrap

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;
    Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

  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>
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

2.6. Configuring multiple JDBC data sources
Copy link

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

Note

When you use the Hibernate ORM extension, you can add only one persistent data storage unit to your application. The persistent data storage unit managed by the Hibernate ORM extension uses the default JDBC data source type.

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 name of the data source. For example, if you choose users as the name of the data source, the fully qualified reference of your data source is quarkus.datasource.users.
    • The db-kind property that matches the type of the data source
    • The quarkus.datasource.username that specifies the username for the data source
    • The quarkus.datasource.jdbc.url that specifies the JDBC connection URL of the data source
    • The quarkus.datasource.jdbc.min-size property that specifies the minimum number of connections that are maintained in the connection pool of the data source

    • The quarkus.datasource.jdbc.max-size property that specifies the maximum number of connections that are maintained in the connection pool of the data source

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

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

quarkus.datasource.users.db-kind=h2
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
      Copy to Clipboard Toggle word wrap

  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;
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat