Datasource Guide

Many projects that use data require connections to a database. The main way of obtaining connections to a database is to use a datasource.

In Quarkus, the out of the box datasource and connection pooling implementation is Agroal.

This guide will explain how to:

  • configure a datasource, or multiple datasources

  • how to obtain a reference to those datasources in code

Prerequisites

To complete this guide, you need:

  • less than 10 minutes

  • an IDE

  • JDK 1.8+ installed with JAVA_HOME configured appropriately

  • Apache Maven 3.5.3+

Creating the Maven project

First, we need a new project. Create a new project with the following command:

mvn io.quarkus:quarkus-maven-plugin:0.15.0:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=agroal-datasources\
    -DclassName="org.acme.datasource.GreetingResource" \
    -Dpath="/hello"

It generates:

  • the Maven structure

  • a landing page accessible on http://localhost:8080

  • example Dockerfile files for both native and jvm modes

  • the application configuration file

  • an org.acme.datasource.GreetingResource resource

  • an associated test

Adding maven dependencies

Next, you will need to add the quarkus-agroal dependency to your project.

You can add it using a simple Maven command:

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

Agroal comes as a transitive dependency of the Hibernate ORM extension so if you are using Hibernate ORM, you don’t need to add the Agroal extension dependency explicitly.

You will also need to add the database connector library of choice.

Quarkus provides driver extensions for:

  • H2 - jdbc-h2

  • PostgreSQL - jdbc-postgresql

  • MariaDB (and MySQL) - jdbc-mariadb

  • Microsoft SQL Server - jdbc-mssql

Note

In JVM mode, simply adding your driver of choice is sufficient. Extensions are mostly useful to support GraalVM native images.

As usual, you can install the extension using add-extension.

To install the PostgreSQL driver dependency for instance, just run the following command:

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

Configuring the datasource

Once the dependencies are added to your pom.xml file, you’ll need to configure Agroal.

This is done in the src/main/resources/application.properties file.

A viable configuration file would be:

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

There are other configuration options, detailed below.

Injecting a Datasource

Because Quarkus uses CDI, injecting a datasource is very simple:

@Inject
AgroalDataSource defaultDataSource;

In the above example, the type is AgroalDataSource which is a subtype of javax.sql.DataSource. Because of this, you can also use javax.sql.DataSource.

Multiple Datasources

Agroal allows you to configure multiple datasources. It works exactly the same way as a single datasource, with one important change: a name.

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

quarkus.datasource.users.driver=org.h2.Driver
quarkus.datasource.users.url=jdbc:h2:tcp://localhost/mem:users
quarkus.datasource.users.username=username1
quarkus.datasource.users.min-size=1
quarkus.datasource.users.max-size=11

quarkus.datasource.inventory.driver=org.h2.Driver
quarkus.datasource.inventory.url=jdbc:h2:tcp://localhost/mem:inventory
quarkus.datasource.inventory.username=username2
quarkus.datasource.inventory.min-size=2
quarkus.datasource.inventory.max-size=12

Notice there’s an extra bit in the key. The syntax is as follows: quarkus.datasource.[optional name.][datasource property].

Named Datasource Injection

When using multiple datasources, each DataSource also has the io.quarkus.agroal.DataSource qualifier with the name of the datasource in the property as the value. Using the above properties to configure three different datasources, you can also inject each one as follows:

@Inject
AgroalDataSource defaultDataSource;

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

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

Agroal Configuration Reference

Configuration key Java type Example

quarkus.datasource.driver

String (class name)

org.h2.Driver, com.mysql.jdbc.Driver

quarkus.datasource.url

String (JDBC Connection URL)

jdbc:h2:tcp://localhost/mem:default, jdbc:mysql://hostname:port/dbname

quarkus.datasource.username

String

Fred, Bill, inventory_user

quarkus.datasource.password

String

correct horse battery staple, Tr0ub4dor&3

quarkus.datasource.min-size

Integer

5, 12, 42

quarkus.datasource.max-size

Integer

5, 12, 42

quarkus.datasource.initial-size

Integer

5, 12, 42

quarkus.datasource.background-validation-interval

java.time.Duration

PT3M, PT56S,

quarkus.datasource.acquisition-timeout

java.time.Duration

PT3M, PT56S - see note below

quarkus.datasource.leak-detection-interval

java.time.Duration

PT3M, PT56S - see note below

quarkus.datasource.idle-removal-interval

java.time.Duration

PT3M, PT56S - see note below

quarkus.datasource.transaction-isolation-level

io.quarkus.agroal.runtime.TransactionIsolationLevel (enum)

none, read-committed, read-uncommitted, repeatable-read, serializable

quarkus.datasource.xa

Boolean

True or False

Note

The format for durations uses the standard java.time format.

You can learn more about it in the Duration#parse() javadoc.