By Version

Dev Services for Databases

Enabling / Disabling Dev Services for Database
- Proprietary Databases - License Acceptance
Database Vendor Specific Configuration
Connect To Database Run as a Dev Service
Configuration Reference

When testing or running in dev mode Quarkus can provide you with a zero-config database out of the box, a feature we refer to as Dev Services. Depending on your database type you may need Docker installed in order to use this feature. Dev Services is supported for the following databases:

DB2 (container) (requires license acceptance)
Derby (in-process)
H2 (in-process)
MariaDB (container)
Microsoft SQL Server (container) (requires license acceptance)
MySQL (container)
Oracle Express Edition (container)
PostgreSQL (container)

If you want to use Dev Services then all you need to do is include the relevant extension for the type of database you want (either reactive or JDBC, or both). Don’t configure a database URL, username and password - Quarkus will provide the database and you can just start coding without worrying about config.

Production databases need to be configured as normal, so if you want to include a production database config in your application.properties and continue to use Dev Services we recommend that you use the %prod. profile to define your database settings.

Enabling / Disabling Dev Services for Database

Dev Services for databases automatically starts a database server in dev mode and when running tests. So, you don’t have to start a server manually. The application is configured automatically.

You can disable the automatic database start in application.properties via:

quarkus.devservices.enabled=false
# OR
quarkus.datasource.devservices.enabled=false

Dev Services for databases relies on Docker to start the server (except for H2 and Derby which are run in process). If your environment does not support Docker, you will need to start the server manually, or connect to an already running server.

Proprietary Databases - License Acceptance

If you are using a proprietary database such as DB2 or MSSQL you will need to accept the license agreement. To do this create a src/main/resources/container-license-acceptance.txt files in your project and add a line with the image name and tag of the database. By default, Quarkus uses the default image for the current version of Testcontainers, if you attempt to start Quarkus the resulting failure will tell you the exact image name in use for you to add to the file.

An example file is shown below:

src/main/resources/container-license-acceptance.txt

ibmcom/db2:11.5.0.0a
mcr.microsoft.com/mssql/server:2017-CU12

Database Vendor Specific Configuration

All services based on containers are run using Testcontainers but Quarkus is not using the Testcontainers JDBC driver. Thus, even though extra JDBC URL properties can be set in your application.properties file, specific properties supported by the Testcontainers JDBC driver such as TC_INITSCRIPT, TC_INITFUNCTION, TC_DAEMON, TC_TMPFS are not supported.

Quarkus can support specific properties sent to the container itself though, e.g. this is the case for TC_MY_CNF which allows to override the MariaDB/MySQL configuration file.

Overriding the MariaDB/MySQL configuration would be done as follows:

quarkus.datasource.devservices.container-properties.TC_MY_CNF=testcontainers/mysql-conf

This support is database specific and needs to be implemented in each dev service specifically.

Connect To Database Run as a Dev Service

You can connect to a database running as a Dev Service as you would do with any database running inside a Docker container.

Database Username Password Database name

Database	Username	Password	Database name
PostgreSQL, MariaDB, MySQL, IBM Db2, H2	`quarkus` for the default datasource or name of the datasource	`quarkus`	`quarkus`
Microsoft SQL Server	`SA`	`Quarkus123`

PostgreSQL, MariaDB, MySQL, IBM Db2, H2

quarkus for the default datasource or name of the datasource

quarkus

Microsoft SQL Server

SA

Quarkus123

The Microsoft SQL Server Testcontainer doesn’t support defining the username or database name. It also requires a strong password.

For databases supporting it (i.e. all of them except Microsoft SQL Server for which it is only possible to override the password), you can override the database name, username and password used by the Dev Service.

See Configuration Reference for more information.

Keep in mind that, except if configured otherwise (see below), a Dev Service runs on a random port. For instance, when you run PostgreSQL as a Dev Service and have psql installed on the host, you can connect via:

psql -h localhost -p <random port> -U quarkus

The random port can be found with docker ps

docker ps

# returns something like this:

CONTAINER ID   IMAGE           [..]    PORTS                                         [..]
b826e3a168c4   postgres:14.2   [..]    0.0.0.0:49174->5432/tcp, :::49174->5432/tcp   [..] (1)

1	The random port is `49174`.

You can require a fixed port for a database Dev Service using:

quarkus.datasource.devservices.port=<your fixed port> (1)

quarkus.datasource."datasource-name".devservices.port=<your fixed port> (2)

1	Fixed port for the default datasource.
2	Fixed port for a named datasource.

docker ps allows for more advanced retrieval of container information using the --format argument. For example, to get the running container ID, the image, the labels and the ports, the following command can be used:

docker ps --format "table {{.ID}}\t{{.Image}}\t{{.Labels}}\t{{.Ports}}

An example output using Dev Services for PostgreSQL is the following:

CONTAINER ID   IMAGE          LABELS                                                                        PORTS
a7034c91a392   postgres:14    org.testcontainers.sessionId=xyz,datasource=default,org.testcontainers=true   0.0.0.0:49154->5432/tcp, :::49154->5432/tcp

In the labels tab, we see that Quarkus added the datasource label, which can be very useful in differentiating containers when multiple Dev Services have been started.

Configuration Reference

Dev Services for Databases support the following configuration options:

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.datasource.devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_ENABLED`	boolean
`quarkus.datasource.devservices.image-name` The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME`	string
`quarkus.datasource.devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_PORT`	int
`quarkus.datasource.devservices.command` The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_COMMAND`	string
`quarkus.datasource.devservices.db-name` The name of the database to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_DB_NAME`	string
`quarkus.datasource.devservices.username` The username to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_USERNAME`	string
`quarkus.datasource.devservices.password` The password to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_PASSWORD`	string
`quarkus.datasource.devservices.init-script-path` Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_INIT_SCRIPT_PATH`	string
`quarkus.datasource.devservices.container-properties` Generic properties that are passed for additional container configuration. Properties defined here are database specific and are interpreted specifically in each database dev service implementation. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_PROPERTIES`	`Map<String,String>`
`quarkus.datasource.devservices.properties` Generic properties that are added to the database connection URL. Environment variable: `QUARKUS_DATASOURCE_DEVSERVICES_PROPERTIES`	`Map<String,String>`
`quarkus.datasource."datasource-name".devservices.enabled` If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_ENABLED`	boolean
`quarkus.datasource."datasource-name".devservices.image-name` The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_IMAGE_NAME`	string
`quarkus.datasource."datasource-name".devservices.container-properties` Generic properties that are passed for additional container configuration. Properties defined here are database specific and are interpreted specifically in each database dev service implementation. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_CONTAINER_PROPERTIES`	`Map<String,String>`
`quarkus.datasource."datasource-name".devservices.properties` Generic properties that are added to the database connection URL. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PROPERTIES`	`Map<String,String>`
`quarkus.datasource."datasource-name".devservices.port` Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PORT`	int
`quarkus.datasource."datasource-name".devservices.command` The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_COMMAND`	string
`quarkus.datasource."datasource-name".devservices.db-name` The name of the database to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_DB_NAME`	string
`quarkus.datasource."datasource-name".devservices.username` The username to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_USERNAME`	string
`quarkus.datasource."datasource-name".devservices.password` The password to use if this Dev Service supports overriding it. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PASSWORD`	string
`quarkus.datasource."datasource-name".devservices.init-script-path` Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby Database) then this has no effect. Environment variable: `QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_INIT_SCRIPT_PATH`	string

Configuration property

Type

Default

quarkus.datasource.devservices.enabled

If DevServices has been explicitly enabled or disabled. DevServices is generally enabled by default, unless there is an existing configuration present. When DevServices is enabled Quarkus will attempt to automatically configure and start a database when running in Dev or Test mode.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_ENABLED

boolean

quarkus.datasource.devservices.image-name

The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_IMAGE_NAME

string

quarkus.datasource.devservices.port

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PORT

int

quarkus.datasource.devservices.command

The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_COMMAND

string

quarkus.datasource.devservices.db-name

The name of the database to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_DB_NAME

string

quarkus.datasource.devservices.username

The username to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_USERNAME

string

quarkus.datasource.devservices.password

The password to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PASSWORD

string

quarkus.datasource.devservices.init-script-path

Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_INIT_SCRIPT_PATH

string

quarkus.datasource.devservices.container-properties

Generic properties that are passed for additional container configuration. Properties defined here are database specific and are interpreted specifically in each database dev service implementation.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_CONTAINER_PROPERTIES

Map<String,String>

quarkus.datasource.devservices.properties

Generic properties that are added to the database connection URL.

Environment variable: QUARKUS_DATASOURCE_DEVSERVICES_PROPERTIES

Map<String,String>

quarkus.datasource."datasource-name".devservices.enabled

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_ENABLED

boolean

quarkus.datasource."datasource-name".devservices.image-name

The container image name to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_IMAGE_NAME

string

quarkus.datasource."datasource-name".devservices.container-properties

Generic properties that are passed for additional container configuration. Properties defined here are database specific and are interpreted specifically in each database dev service implementation.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_CONTAINER_PROPERTIES

Map<String,String>

quarkus.datasource."datasource-name".devservices.properties

Generic properties that are added to the database connection URL.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PROPERTIES

Map<String,String>

quarkus.datasource."datasource-name".devservices.port

Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PORT

int

quarkus.datasource."datasource-name".devservices.command

The container start command to use, for container based DevServices providers. If the provider is not container based (e.g. a H2 Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_COMMAND

string

quarkus.datasource."datasource-name".devservices.db-name

The name of the database to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_DB_NAME

string

quarkus.datasource."datasource-name".devservices.username

The username to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_USERNAME

string

quarkus.datasource."datasource-name".devservices.password

The password to use if this Dev Service supports overriding it.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_PASSWORD

string

quarkus.datasource."datasource-name".devservices.init-script-path

Path to a SQL script that will be loaded from the classpath and applied to the Dev Service database If the provider is not container based (e.g. a H2 or Derby Database) then this has no effect.

Environment variable: QUARKUS_DATASOURCE__DATASOURCE_NAME__DEVSERVICES_INIT_SCRIPT_PATH

string