Quarkus Dev Services PostgreSQL: local convenience and the Docker dependency

The problem: Quarkus dev mode stops without Docker

You clone a Quarkus service that uses PostgreSQL, run ./mvnw quarkus:dev, and the build stops with a Docker connection error. Quarkus Dev Services tried to launch a PostgreSQL container and found no Docker daemon. This happens on restricted laptops, CI agents without Docker-in-Docker, or workstations where Docker Desktop is not running.

What Dev Services does automatically

When the quarkus-jdbc-postgresql extension is on the classpath, Quarkus Dev Services starts a PostgreSQL container in dev mode and in @QuarkusTest runs. It configures the datasource, maps a host port, and creates the database so Hibernate can generate the schema. You do not write docker run commands.

Configuration you can control

Tune the container through application.properties using the quarkus.datasource.devservices.* prefix.

# src/main/resources/application.properties
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=appuser
quarkus.datasource.password=apppass

# Dev Services overrides
quarkus.datasource.devservices.image-name=postgres:15-alpine
quarkus.datasource.devservices.database-name=mydb
quarkus.datasource.devservices.port=5433

With port 5433 fixed, connect after startup with psql -h localhost -p 5433 -U appuser -d mydb.

Worked example: disable Dev Services when Docker is unavailable

If your CI agent cannot reach a Docker daemon, dev mode and database tests fail at startup. Disable Dev Services for that environment:

quarkus.datasource.devservices.enabled=false

Then point the datasource at an external PostgreSQL instance or skip database-dependent tests. To verify the container is not starting, run ./mvnw quarkus:dev from the project root and confirm the console does not print a line such as Starting container PostgreSQL. The application will log a connection failure unless an external datasource is configured.

Required permissions: the terminal user must be able to execute docker commands, typically through membership in the docker group. The Maven command itself does not need root.

Trade-offs and limitations

• Development and test only. Dev Services is disabled in production builds. Do not rely on it for staging or production databases.
• Docker dependency. Without a reachable Docker daemon, the application fails to start unless you set quarkus.datasource.devservices.enabled=false.
• Limited container customization. The extension exposes image, database name, credentials, and port. Mounting custom config files or changing the entrypoint requires manual Testcontainers usage.
• Port collisions. A fixed quarkus.datasource.devservices.port blocks startup if another service already uses that port.

Actionable closing

1. Add the quarkus-jdbc-postgresql dependency to your Quarkus project.
2. Run ./mvnw quarkus:dev and watch for the container start message and mapped port.
3. Connect to the reported localhost port with psql or your GUI client to inspect the schema.
4. Write @QuarkusTest classes; Dev Services provisions an isolated database per suite.
5. If Docker is unavailable, set quarkus.datasource.devservices.enabled=false and point the datasource at an external PostgreSQL instance.

Treat Dev Services as a local-development convenience, not a deployment strategy. Keep Docker available on your workstation, and disable the feature in environments that cannot run containers.