jOOQ: SQL con tipos seguros como DSL de Kotlin

jOOQ le da la vuelta a la filosofia habitual de los ORM. En lugar de esconder el SQL detras de objetos y confiar en que las consultas generadas sean razonables, jOOQ abraza el SQL como un lenguaje de primera clase y te ofrece un DSL de Kotlin fluido y con tipos seguros que lo refleja casi palabra por palabra. Escribes `dsl.select(...).from(TABLE).where(FIELD.eq(x)).fetch()`, y lo que lees es exactamente el SQL que se ejecuta. No hay magia de carga perezosa, ni sorpresas ocultas de N+1, ni una capa de traduccion opaca entre tu intencion y la base de datos. Para equipos que de verdad valoran su SQL, esto es liberador: conservas todo el poder expresivo de tu dialecto mientras ganas la red de seguridad del compilador.

La caracteristica que lo define es la generacion de codigo. jOOQ se conecta a tu esquema real (o lee tus migraciones) en tiempo de compilacion y genera clases Kotlin/Java para cada tabla, columna, secuencia y rutina. Una tabla como `users` se convierte en un objeto `USERS`, y cada columna se vuelve un `Field` fuertemente tipado, como `USERS.EMAIL` de tipo `Field<String?>` y `USERS.AGE` de tipo `Field<Int?>`. Como son objetos reales con tipos reales, tu IDE autocompleta los nombres de columna, las herramientas de refactorizacion los renombran con seguridad, y una columna que ya no existe en el esquema se convierte en un error de compilacion en vez de una excepcion en tiempo de ejecucion. El codigo generado es el puente entre tu base de datos en evolucion y tu Kotlin tipado estaticamente.

Por eso el SQL verificado en compilacion supera de forma tan contundente a las consultas como cadenas. Una cadena escrita a mano como `"SELECT emial FROM users WHERE age > ?"` compila sin problema y revienta solo cuando una peticion real la alcanza, quiza semanas despues, quiza solo para ciertas entradas. Con jOOQ, `USERS.EMIAL` sencillamente no existe, asi que la compilacion falla en el momento en que escribes el error. La misma proteccion cubre las incompatibilidades de tipo: no puedes comparar por accidente un campo `String` con un `Int`, porque `USERS.EMAIL.eq(42)` no pasara la verificacion de tipos. La categoria de errores en la que el SQL se desincroniza del esquema practicamente desaparece.

Obtener resultados es donde jOOQ se mantiene pragmatico. Un `fetch()` simple devuelve un `Result<Record>`, una lista ordenada en memoria de registros que puedes recorrer, donde cada `Record` expone accesores tipados como `record[USERS.EMAIL]`. Los registros son flexibles e ideales para consultas ad-hoc con forma de proyeccion que no encajan limpiamente en una sola clase. Cuando si tienes un tipo destino, `fetchInto(UserDto::class.java)` mapea las columnas de cada fila a los campos del DTO por nombre, dandote un `List<UserDto>` limpio sin desempaquetado manual. Tambien hay terminales de conveniencia: `fetchOne()` para como mucho una fila (nullable), `fetchSingle()` cuando se requiere exactamente una, y `fetchAny()` para la primera coincidencia.

En una aplicacion Spring Boot 3, jOOQ encaja sin fricciones. El starter `org.springframework.boot:spring-boot-starter-jooq` configura un bean `DSLContext` sobre tu `DataSource` existente, y participa en la gestion de `@Transactional` de Spring como cualquier otro componente de acceso a datos. Simplemente inyectas `DSLContext` en una clase repositorio y escribes consultas. Como jOOQ ejecuta JDBC plano por debajo, convive en paz con Spring Data JPA en el mismo proyecto: muchos equipos usan JPA para el CRUD sencillo y recurren a jOOQ para las consultas analiticas y de reportes espinosas donde el control preciso del SQL mas importa.

La API de jOOQ es fundamentalmente JDBC bloqueante, lo que merece una nota honesta en una base de codigo consciente de las coroutines. Para llamar una consulta de jOOQ desde una funcion `suspend` sin bloquear tu event loop o tus hilos de peticion, envuelve la llamada en `withContext(Dispatchers.IO)`, que mueve el trabajo JDBC bloqueante a un pool de hilos dimensionado para I/O. jOOQ si ofrece una variante reactiva y no bloqueante construida sobre R2DBC, pero para el servicio Spring MVC tipico el patron `Dispatchers.IO` es el puente correcto mas simple entre el SQL bloqueante y el Kotlin suspendible.

El DSL se compone igual que lo hace el SQL, que es la verdadera recompensa a escala. Los joins (`.join(ORDERS).on(ORDERS.USER_ID.eq(USERS.ID))`), los agregados (`count()`, `sum()`, `groupBy`, `having`), las funciones de ventana, las expresiones de tabla comun y `UNION` se leen con naturalidad y mantienen sus tipos verificados de extremo a extremo. Como las consultas son expresiones Kotlin ordinarias, puedes construirlas dinamicamente, agregando condiciones con `DSL.and`/`DSL.or`, o ensamblando una lista de objetos `Condition` a partir de parametros de filtro opcionales, sin recurrir nunca a la fragil concatenacion de cadenas. El SQL dinamico se vuelve simplemente datos dinamicos.

En resumen, jOOQ es la herramienta a la que recurrir cuando el SQL es una caracteristica de tu sistema y no un detalle de implementacion que abstraer. Cambias la configuracion inicial de un paso de generacion de codigo por consultas que son legibles, seguras ante refactorizaciones y verificadas contra tu esquema real por el compilador. Cuando tu aplicacion se apoya fuertemente en consultas complejas, reportes o caracteristicas especificas de la base de datos, ese intercambio vale enormemente la pena: conservas la precision del SQL crudo y dejas atras toda la categoria de errores de tipeo y desincronizacion.

import org.jooq.DSLContext
import org.springframework.stereotype.Repository
// generated tables: import com.example.db.tables.Users.USERS

data class UserDto(val id: Long, val email: String, val age: Int)

@Repository
class UserRepository(private val dsl: DSLContext) {

    // SELECT id, email, age FROM users WHERE age >= ? ORDER BY email
    fun findAdults(minAge: Int): List<UserDto> =
        dsl.select(USERS.ID, USERS.EMAIL, USERS.AGE)
            .from(USERS)
            .where(USERS.AGE.ge(minAge))   // USERS.AGE.ge("x") would NOT compile
            .orderBy(USERS.EMAIL.asc())
            .fetchInto(UserDto::class.java)

    // fetchOne() returns a nullable single row
    fun findByEmail(email: String): UserDto? =
        dsl.selectFrom(USERS)
            .where(USERS.EMAIL.eq(email))
            .fetchOne()
            ?.into(UserDto::class.java)
}

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import org.jooq.DSLContext
import org.jooq.impl.DSL.count
// import com.example.db.tables.Users.USERS

class StatsService(private val dsl: DSLContext) {

    // suspend wrapper so blocking JDBC runs off the request thread
    suspend fun usersPerDomain(): Map<String, Int> = withContext(Dispatchers.IO) {
        val domain = USERS.EMAIL.substring(USERS.EMAIL.position("@").plus(1))
        dsl.select(domain, count())
            .from(USERS)
            .groupBy(domain)
            .fetch()                       // Result<Record2<String, Int>>
            .associate { record ->
                record.value1() to record.value2()
            }
    }
}

// Illustration of the 'dynamic SQL = dynamic data' idea using plain Kotlin.
// In real jOOQ these predicates would be org.jooq.Condition objects.
data class Filter(val minAge: Int?, val domain: String?)

fun main() {
    data class User(val email: String, val age: Int)
    val users = listOf(
        User("ana@acme.com", 31),
        User("bob@other.io", 19),
        User("cat@acme.com", 42),
    )

    val filter = Filter(minAge = 21, domain = "acme.com")

    // Collect only the predicates that apply, then AND them together.
    val predicates = buildList<(User) -> Boolean> {
        filter.minAge?.let { min -> add { it.age >= min } }
        filter.domain?.let { d -> add { it.email.endsWith("@" + d) } }
    }

    val result = users.filter { user -> predicates.all { it(user) } }
    result.forEach { println(it.email + " / " + it.age) }
}