Automating Database Setup with Quarkus Dev Services

Eliminating Manual Database Provisioning

Setting up a local database for every developer on a team often leads to "it works on my machine" syndrome due to mismatched versions, missing schemas, or incorrect credentials. The goal is to move from manual installation and configuration to a zero-config environment where the database lifecycle is managed by the application framework.

Quarkus Dev Services solves this by automatically detecting the database extension in your project and launching a corresponding container via Docker when you enter development mode. This removes the need to maintain local application.properties files for database URLs and passwords during the initial build phase.

Prerequisites

• Docker Desktop or Colima: A running Docker daemon is required. Dev Services cannot provision a database without a container runtime.
• Java 17+ and Maven/Gradle: Standard Quarkus environment requirements.
• Quarkus Project: An existing project with a database extension (e.g., quarkus-jdbc-postgresql).

Implementing Dev Services

Dev Services are active by default when you include a database extension and do not provide a manual datasource configuration. Follow these steps to enable and verify the feature.

1. Add the Database Extension

Run the following command in your terminal to add the PostgreSQL extension (replace postgresql with mysql or mariadb if needed):

./mvnw quarkus:ext add quarkus-jdbc-postgresql

2. Avoid Manual Configuration

To trigger Dev Services, do not define quarkus.datasource.jdbc.url or quarkus.datasource.username in your src/main/resources/application.properties. If these properties are present, Quarkus assumes you are providing your own database and will disable Dev Services for that datasource.

3. Launch Dev Mode

Start your application using the Quarkus development command:

./mvnw quarkus:dev

Verification and Diagnostics

When the application starts, monitor the console output. You should see a log entry similar to the following:

I [org.quarkus.runner. QuarkusMain] (main) Dev Services started PostgreSQL container

To verify the connection is functional, you can create a simple health check or a REST endpoint that performs a count() query on a JPA entity. If the endpoint returns a successful response, the framework has successfully injected the dynamic connection details into the application context.

Comparison: Dev Services vs. Manual Config

Feature	Dev Services	Manual Configuration
Setup Time	Instant (Auto-pull)	Manual Install/Config
Port Management	Dynamic (Prevents conflicts)	Static (Risk of port collisions)
Lifecycle	Tied to process	Persistent/Manual stop
Consistency	Identical across team	Varies by local install

Overriding Dev Services

While Dev Services are ideal for rapid iteration, you may need to connect to a shared staging database or a specific local instance for debugging. To override the automatic container, add the following to your application.properties:

quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/my_custom_db
quarkus.datasource.username=admin
quarkus.datasource.password=secret

Once these properties are detected, Quarkus will stop attempting to start a Docker container and will instead use the provided credentials.

Limitations and Risks

• Startup Latency: The first time you run the app, there is a delay while Docker pulls the database image.
• Resource Consumption: Each active Dev Services container consumes RAM. Ensure your Docker resource limits are sufficient for the number of services running.
• Network Isolation: Because the container is managed by Quarkus, accessing the database from an external GUI tool (like pgAdmin) requires you to check the logs for the randomly assigned host port.

Rollback Procedure

If Dev Services cause stability issues or conflict with other local services, you can disable them globally for the session by setting the following environment variable before running the app:

export QUARKUS_DEV_SERVICES_ENABLED=false

Alternatively, removing the database extension via ./mvnw quarkus:ext remove [extension-name] will stop the service from being requested.