Decisiones de arquitectura

ADR-0002: Generación de código jOOQ en perfil manual, con fuentes versionadas

Estado: Aceptado · Fecha: 2026-09-24

Contexto

jOOQ genera clases Java a partir del esquema. Hay tres formas de obtenerlas:

  1. DDLDatabase: parsear los .sql de migración sin base de datos viva.
  2. Generar en cada build contra un PostgreSQL efímero (Testcontainers).
  3. Generar a mano contra el PostgreSQL local y versionar el resultado.

La opción 1 no sirve aquí: DDLDatabase no soporta TEXT con UNIQUE (jOOQ#9336) y este esquema usa text en todas sus columnas de cadena. Tampoco interpretaría uuidv7(), btree_gist ni las restricciones de exclusión.

La opción 2 obliga a que cualquier build alcance un Docker con red: un docker build no lo tiene, y un runner de CI tampoco necesariamente.

Decisión

Perfil de Maven jooq-codegen, no ligado a ninguna fase del build normal. Migra el PostgreSQL local con Flyway y genera en com.sineltek.lis.jooq, dentro de src/main/java. Las fuentes generadas se versionan.

docker compose up -d db      # make dev
./mvnw -Pjooq-codegen generate-sources   # make jooq-codegen

Regla derivada: ninguna migración se da por terminada hasta que el código regenerado que la acompaña está en el mismo commit.

Consecuencias

  • mvn verify, docker build y CI no necesitan PostgreSQL.
  • El código generado es revisable en el diff: un cambio de esquema se ve en Java. − El código generado ocupa espacio en el repositorio y ensucia los diffs de migración. − Si alguien cambia una migración y olvida regenerar, el esquema y el código divergen. Lo mitiga la regla del commit único, y un test de integración lo detecta en cuanto se ejecuta.

Alternativas descartadas

DDLDatabase (no soporta el esquema) · codegen contra Testcontainers en cada build (rompe docker build y CI, y alarga cada compilación por un cambio que ocurre pocas veces).