Vai al contenuto

ADR-0003: PostgreSQL reale via Testcontainers (no H2 in test)

Stato: Accettato Data: 2026-05-20

Contesto

Per i test di integrazione abbiamo bisogno di un database. Opzioni:

  1. H2 in-memory — veloce, zero setup, ma sintassi/comportamenti diversi da PostgreSQL.
  2. PostgreSQL embedded (es. EmbeddedPostgres) — uguale ma processi nativi su disco.
  3. Testcontainers + PostgreSQL — container Docker effimero, identico alla prod.

Decisione

Usiamo Testcontainers con PostgreSQLContainer<>("postgres:16-alpine") e @ServiceConnection di Spring Boot 3.1+.

Setup riusabile in AbstractIntegrationTest:

@Container
@ServiceConnection
static final PostgreSQLContainer<?> POSTGRES = new PostgreSQLContainer<>("postgres:16-alpine")
        .withReuse(true);

Conseguenze

Positive

  • I test girano contro lo stesso engine, versione e dialetto della produzione.
  • Le migration Flyway sono validate dal vero.
  • Tipi PostgreSQL nativi (UUID, JSONB, array) funzionano nei test.
  • Niente più bug "passa H2, fallisce in prod".

Negative

  • Richiede Docker installato — primo run lento (download immagine).
  • Tempo di avvio del container: ~3-5s a primo test, poi .withReuse(true) lo riusa.
  • CI deve avere Docker (GitHub Actions runner Linux ce l'ha di default).

Neutre

  • Il developer deve avere Docker desktop / engine localmente.

Alternative valutate

  • H2 — scartato: divergenza con PostgreSQL su tipi, funzioni date, JSON.
  • Embedded PostgreSQL — scartato: processi nativi più fragili e non isolati.