Skip to content
javahacks.dev
Quarkus

How to Use Quarkus Dev Services for Databases and Brokers

Let Quarkus start a PostgreSQL, Kafka or Redis container in dev mode and tests when no connection is configured, and learn how to pin images and turn it off.

6 min read
Summarize in AI
Flat illustration of startup time of a JVM compared with a native image, with the Quarkus, Docker, Spring Boot and OpenJDK logos.

Tutorials that begin with "first install PostgreSQL" lose half their readers. Quarkus Dev Services remove that step: if the application needs a database and you have not said where it is, Quarkus starts one in a container, wires the connection and tears it down on exit. This post shows how it behaves and how to control it. It follows the setup in the Quarkus tutorial and uses the dev loop from dev mode and continuous testing.

See it work

Add the extensions:

Shell
./mvnw quarkus:add-extension -Dextensions='hibernate-orm-panache,jdbc-postgresql'

Set only what must be explicit:

src/main/resources/application.propertiesproperties
quarkus.datasource.db-kind=postgresql
quarkus.hibernate-orm.database.generation=drop-and-create

Start ./mvnw quarkus:dev. The log shows a container being pulled and started, and the connection details are injected for you. There is no JDBC URL anywhere in your files. Stop dev mode and the container goes away.

Which resources have Dev Services

Many extensions provide one: databases (PostgreSQL, MySQL, MariaDB, Oracle and others), Kafka and AMQP brokers, Redis, MongoDB, Keycloak for OIDC, Elasticsearch and more. The Dev Services guide lists them. The Dev UI shows the running containers and their connection details.

Control the images

By default Quarkus picks a recent stable image for the database. Pin the version to match production:

properties
quarkus.datasource.devservices.image-name=postgres:17
quarkus.datasource.devservices.port=5433
quarkus.datasource.devservices.reuse=true

A fixed port is handy when you want to connect a client tool. reuse keeps the container between runs so startup is quicker, and data persists until you remove it. Pinning the image to your production major version prevents a class of bug that only shows after deployment; the same reasoning drives real-database tests.

Load test data

Provide an import script that Hibernate runs at startup in dev and test:

properties
%dev.quarkus.hibernate-orm.sql-load-script=import-dev.sql
%test.quarkus.hibernate-orm.sql-load-script=import-test.sql

Files go in src/main/resources. The %dev. and %test. prefixes keep demo data out of production.

Turn it off or point elsewhere

Dev Services step aside when you configure the connection:

properties
%dev.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/shop

With a URL set for the profile, nothing starts. To disable them all, for example on a machine without Docker:

properties
quarkus.devservices.enabled=false

Tests use them too

A @QuarkusTest gets the same containers, shared across the test run. That means a repository test runs against real PostgreSQL without any @Container field or JUnit extension. Compare with the Spring approach, where you declare the container and @ServiceConnection, in a practical Java testing strategy.

When Docker is not available

Without a reachable container runtime, Dev Services log a warning and the application fails to find its datasource. Install Docker or Podman, or set the URL by hand. Rootless Podman works with the socket enabled; set DOCKER_HOST as described in the Testcontainers fix.

What happens when you start without any URL

Dev Services starts the containers a dependency needs when you run in dev or test mode and have not configured the connection yourself. The shortest demonstration uses a database extension and no URL.

src/main/resources/application.propertiesproperties
quarkus.datasource.db-kind=postgresql
quarkus.hibernate-orm.database.generation=drop-and-create
Shell
./mvnw quarkus:dev

With Docker running, Quarkus starts a PostgreSQL container, injects the JDBC URL, user and password into the datasource and prints the container in its startup output. Stop the application and the container goes away. The point of the feature is what is missing from the configuration: you wrote the database kind and nothing else, and no developer needs a local database, a shared server or a credentials file. If you add a URL for the dev profile, Dev Services steps aside and uses yours, so the opt-out is to configure the thing yourself.

properties
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db.internal:5432/orders
%prod.quarkus.datasource.username=${DB_USER}
%prod.quarkus.datasource.password=${DB_PASSWORD}

The %prod. prefix limits those lines to the production profile, which is why the dev and test runs still start a container. Keep that discipline: configuration for the real database in the %prod profile only, so a developer's laptop never connects to it by accident.

Pin the image and keep the data between restarts

The default image tag follows the extension's choice, which can change when you upgrade Quarkus. Pin it to the major version you run in production, so tests exercise the same database engine.

properties
quarkus.datasource.devservices.image-name=postgres:17-alpine
quarkus.datasource.devservices.reuse=true
quarkus.datasource.devservices.port=5433

With reuse=true, the container survives restarts of the dev mode process and is shared by applications in the same dev session, which makes the restart fast, and the data stays. A fixed port lets you connect a SQL client during development. Use a fixed port only when you need it, since two projects asking for the same port conflict. For a clean slate, stop the container with docker rm -f and start again.

Load test data on startup

Hibernate ORM loads an import.sql file from the class path when the schema is created in dev and test modes, which is the simplest way to seed data.

src/main/resources/import.sqlSQL
INSERT INTO customer (id, name) VALUES (1, 'Ada');
INSERT INTO customer (id, name) VALUES (2, 'Grace');

For a script that is not tied to Hibernate, or for other extensions, point the Dev Services datasource at an initialisation script with the init-script-path property of the datasource's Dev Services configuration, available in recent Quarkus 3 releases; check its exact name against the version in your build. Keep seed data small and the same in every environment where it is used, because tests that rely on a specific row break the first time someone edits the seed file. Prefer tests that create the rows they need.

Brokers and other services

The same idea applies to Kafka, RabbitMQ, Redis, MongoDB, Keycloak and others: add the extension, leave the connection unset, and a container is started. Quarkus detects when one container can serve several applications and shares it. Disable a particular service when you want to point at your own broker:

properties
quarkus.kafka.devservices.enabled=false
kafka.bootstrap.servers=localhost:9092

Turn all Dev Services off with quarkus.devservices.enabled=false, for instance in a CI environment that provides its own services. In tests, the containers start once per test run and are shared across test classes, so a suite of 40 integration tests does not start 40 databases. When Docker is not available, Dev Services cannot start and the application reports the failure at startup, naming the extension that needed it. In that case configure the connection explicitly for the profile, or install Docker or a compatible runtime such as Podman, which Quarkus supports.

Where this does not apply

Production configuration has no Dev Services: set real URLs through environment variables, as described in Quarkus for Spring developers. A container started this way has default credentials and is meant to be thrown away. The Dev Services overview and the datasource guide list every devservices property.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.