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:
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.
Configuration Reference
Datasource Dev Services support the following config options:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
---|---|---|
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. |
boolean |
|
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. |
string |
|
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. |
int |
|
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. |
|
|
Generic properties that are added to the database connection URL. |
|
|
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. |
boolean |
|
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. |
string |
|
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. |
|
|
Generic properties that are added to the database connection URL. |
|
|
Optional fixed port the dev service will listen to. If not defined, the port will be chosen randomly. |
int |