Using Quarkus Dev Services for PostgreSQL in Development and Tests

Quick answer: get a PostgreSQL container automatically

When you add the Quarkus JDBC PostgreSQL extension, Dev Services starts a temporary PostgreSQL container the first time the application looks for a datasource in dev or test mode. No manual Docker commands are required.

How Dev Services provisions PostgreSQL

The extension registers a Dev Service implementation that, upon detecting a missing datasource configuration, launches a container using the default image postgres:15. It maps port 5432 on localhost, creates a database named dev, and sets the user and password to quarkus. The resulting JDBC URL is exposed as jdbc:postgresql://localhost:5432/dev and the datasource is available for CDI injection.

Add the extension

# Maven
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jdbc-postgresql</artifactId>
</dependency>
# Gradle
implementation("io.quarkus:quarkus-jdbc-postgresql")

Minimal configuration

# src/main/resources/application.properties
quarkus.datasource.db-kind=postgresql

Inject and use the datasource

import io.agroal.api.AgroalDataSource;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/db")
public class DbResource {

    @Inject
    AgroalDataSource ds;

    @GET
    @Path("/ping")
    @Produces(MediaType.TEXT_PLAIN)
    public String ping() {
        try (var conn = ds.getConnection()) {
            return "Connected: " + conn.getMetaData().getDatabaseProductName();
        } catch (Exception e) {
            return "Error: " + e.getMessage();
        }
    }
}

Verification steps

1. Run the application in dev mode: ./mvnw quarkus:dev (or gradle quarkusDev).
2. Watch the console for a line similar to Starting Dev Service for PostgreSQL and the bound port localhost:5432.
3. Invoke the endpoint, e.g. curl http://localhost:8080/db/ping. A successful response indicates the Dev Service container is reachable.

Limits and common mistakes

• Dev Services is intended only for development and test; it is automatically disabled in production builds unless you explicitly set quarkus.devservices.enabled=true. Enabling it in production can expose unintended containers.
• If you need a customized PostgreSQL (specific extensions, init scripts, or a different version), the default container may not suffice. In that case disable Dev Services (quarkus.devservices.enabled=false) and provide your own container or external database.
• Port conflicts occur when another process already uses 5432 on localhost. Dev Services will fail to start and you will see a bind error in the logs.
• Forgetting to add the JDBC extension or setting an incorrect db-kind will cause the application to fail with a datasource unavailable error.

Turning Dev Services off and using your own container

# src/main/resources/application.properties
quarkus.devservices.enabled=false
# Provide your own connection details, e.g.
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydb
quarkus.datasource.username=myuser
quarkus.datasource.password=mypassword

After disabling, run the dev mode again; the console will no longer show the Dev Service start message, and the application will attempt to connect to the URL you supplied.