La lección anterior terminó con una ironía: BiblioTech tiene un @Transactional sobre prestar que no hace absolutamente nada, porque debajo no hay ninguna base de datos que pueda confirmar o revertir. Toda la persistencia sigue siendo lo que era en el módulo 7: ficheros CSV escritos a mano.

Esta lección los sustituye por una base de datos relacional de verdad.

Hibernate es el ORM más usado del mundo Java, y la implementación de referencia de Jakarta Persistence (antes JPA). Su trabajo es traducir entre dos mundos que no encajan: el de los objetos, con herencia, referencias y navegación; y el de las tablas, con filas, columnas y claves foráneas. Ese trabajo es tedioso, repetitivo y fácil de hacer mal, y por eso existe una herramienta para automatizarlo.

Pero un ORM no es una capa transparente que se pueda usar sin entenderla. Es probablemente la pieza de la que más gente abusa sin saber lo que está pasando: consultas que se multiplican por cien, excepciones que aparecen fuera de la transacción, entidades que se guardan solas sin que nadie llame a save, y esquemas de producción destruidos por una propiedad mal puesta. Todo eso tiene explicación, y esta lección la da.

La ventaja con la que llegas es la de siempre: Hibernate lee @Entity y @Column por reflexión, exactamente igual que tu ExportadorAnotado leía @CampoCsv. Y Spring Data JPA te dará repositorios funcionando sin escribir la implementación, con el mismo Proxy.newProxyInstance de 10-03.

Al terminar sabrás qué automatiza un ORM y qué cuesta; mapearás entidades y relaciones completas; entenderás el contexto de persistencia y los estados de una entidad; sabrás por qué aparece la LazyInitializationException y qué es el problema N+1, con sus soluciones; escribirás consultas JPQL con parámetros —y sabrás por qué concatenar cadenas es una vulnerabilidad—; manejarás transacciones, propagación y bloqueo optimista; y BiblioTech guardará sus datos en H2 con Material, Empleado y Prestamo como entidades reales.

1. El desajuste objeto-relacional
2. Qué se gana y qué se pierde frente a JDBC
3. JDBC en veinte líneas: la línea base
4. JPA frente a Hibernate: especificación e implementación
5. Poner en marcha JPA con H2 en BiblioTech
6. La primera entidad: @Entity, @Table, @Id
7. @GeneratedValue y sus estrategias
8. @Column y el mapeo de tipos
9. @Enumerated: por qué STRING y nunca ORDINAL
10. LocalDate, Instant y los conversores propios
11. @Embeddable y @Embedded
12. Relaciones: los cuatro tipos
13. Lado propietario y mappedBy
14. FetchType: carga perezosa frente a ansiosa
15. La LazyInitializationException
16. El problema N+1
17. Resolverlo: JOIN FETCH y @EntityGraph
18. CascadeType y orphanRemoval
19. El contexto de persistencia y el EntityManager
20. Los cuatro estados de una entidad
21. La comprobación de cambios automática
22. flush y el orden de las operaciones
23. Las operaciones: persist, merge, find, getReference, remove
24. Consultas: JPQL
25. Consultas con nombre, API de criterios y SQL nativo
26. Inyección SQL: por qué nunca se concatena
27. Transacciones: @Transactional con base de datos real
28. Propagación y aislamiento
29. Bloqueo optimista con @Version
30. Cachés de primer y segundo nivel
31. ddl-auto y por qué nunca update en producción
32. Spring Data JPA
33. BiblioTech: de CSV a H2
34. Errores Comunes y Consejos
35. Ejercicios

El problema tiene nombre propio: desajuste de impedancia objeto-relacional (object-relational impedance mismatch). El modelo de objetos y el modelo relacional se inventaron para cosas distintas y no encajan de forma natural.

Los puntos de fricción concretos:

Fíjate en la fila de la herencia, porque es la más brutal: el modelo relacional no tiene herencia. La jerarquía sellada Material de BiblioTech, que en 10-06 permitía switch exhaustivos verificados por el compilador, sencillamente no se puede expresar en SQL. Alguien tiene que decidir cómo se representa, y hay tres estrategias distintas, cada una con sus compromisos.

Y la de la navegación es la que más problemas de rendimiento causa: en Java, prestamo.material().editorial() es gratis; en SQL, cada salto puede ser una consulta. De ahí sale el problema N+1 del apartado 16.

Un ORM (Object-Relational Mapper) es una herramienta que traduce automáticamente entre los dos mundos. No elimina el desajuste: lo gestiona. Y saber que existe es la diferencia entre usar Hibernate bien y sufrirlo.

Con honestidad, porque hay opiniones fuertes en ambos sentidos y las dos tienen razón en parte.

La regla profesional razonable:

• ORM para el CRUD del dominio, que es el 80 % del código de una aplicación de gestión: guardar un préstamo, cargar un empleado, actualizar un material.
• SQL directo (JDBC, JdbcTemplate o jOOQ) para informes, agregaciones complejas y procesos masivos.

Ambas cosas conviven perfectamente en el mismo proyecto, y eso es lo que hace BiblioTech.

Para entender qué automatiza Hibernate, primero hay que ver qué había que escribir. Esto es JDBC puro leyendo préstamos:

Lo que hay ahí, y lo que Hibernate va a eliminar:

1. SQL escrito a mano para cada consulta.
2. Mapeo columna a columna, con getLong, getString, getDate.
3. Conversión de tipos: java.sql.Date a LocalDate, null a Optional.empty().
4. Gestión de recursos: tres try-with-resources anidados.
5. Traducción de excepciones: SQLException a la jerarquía del módulo 6.
6. Nombres de columna como cadenas: "fecha_vencimiento" mal escrito falla en ejecución.

Multiplica eso por las cuarenta consultas de una aplicación real y por las seis entidades, y tendrás varios miles de líneas que no aportan valor y que hay que mantener cada vez que cambia una columna.

JDBC no es malo. Es de bajo nivel. Con Hibernate, esa consulta entera se convierte en:

Y ni siquiera hay que escribir esa línea, como verás en el apartado 32.

Otra confusión clásica que conviene despejar.

Jakarta Persistence (JPA) es una especificación: un conjunto de interfaces y anotaciones estandarizadas, en el paquete jakarta.persistence. Define EntityManager, @Entity, @Id, @OneToMany, JPQL... pero no contiene código que funcione.

Hibernate es una implementación de esa especificación. Es quien de verdad genera el SQL, gestiona el contexto de persistencia y habla con la base de datos.

La recomendación práctica: programa contra JPA siempre que puedas y usa extensiones de Hibernate solo cuando lo necesites de verdad. Es el mismo principio de la fachada que verás con SLF4J en 11-07.

Aviso de versiones, importante. Jakarta EE renombró todos los paquetes javax.* a jakarta.*. Spring Boot 3 y Hibernate 6 usan jakarta.persistence. Si copias un ejemplo con import javax.persistence.Entity, es de Spring Boot 2 o anterior y no compilará. Es el error de copia y pega más frecuente hoy.

Dos dependencias añadidas al pom.xml de 11-02:

Y la configuración en application.yml:

Con eso ya está. Ejecuta:

Y en el arranque verás las condiciones del apartado 19 de 11-02 cumpliéndose: DataSourceAutoConfiguration detecta H2 en el classpath, ve que tú no has definido un DataSource, y lo crea. HibernateJpaAutoConfiguration detecta Hibernate y monta el EntityManagerFactory y el gestor de transacciones. Cero código de configuración.

Dos notas sobre show-sql: es imprescindible mientras aprendes —vas a ver exactamente qué SQL genera Hibernate y eso es la mitad del aprendizaje— y hay que desactivarlo en producción, donde el logging correcto es por SLF4J (11-07):

Convertimos Libro de BiblioTech en una entidad:

Los requisitos que impone JPA a una entidad, y que conviene conocer porque los errores son crípticos:

Y ahí tienes por qué un record no puede ser una entidad JPA: es final, sus campos son final y no tiene constructor sin argumentos. Los record de BiblioTech (Ficha, ResumenSesion) seguirán siendo perfectos como DTO y como proyecciones de consulta, pero las entidades tienen que ser clases mutables. Es un compromiso real del ORM, no un capricho.

Sobre @Table: si no la pones, la tabla se llama como la clase. Ponerla explícitamente es buena práctica, porque Prestamo mapearía a una tabla PRESTAMO, y palabras como ORDER, USER o GROUP son reservadas en SQL y dan errores desconcertantes.

Quién genera la clave primaria. Es una decisión con impacto real en el rendimiento.

La recomendación con Hibernate 6 y una base de datos que soporte secuencias:

El motivo del allocationSize importa: con IDENTITY, Hibernate no puede agrupar inserciones, porque necesita ejecutar cada INSERT para que el motor le devuelva el id. Con SEQUENCE y allocationSize=50, puede acumular 50 inserciones y enviarlas en un lote. En una importación de 10.000 materiales, la diferencia es de minutos.

Para los ejemplos con H2 de esta lección usaremos IDENTITY por simplicidad, pero conoce la razón por la que en producción se prefiere SEQUENCE.

@Column describe la columna. Sus atributos útiles:

Los tipos que JPA mapea automáticamente:

Dos avisos concretos sobre BiblioTech:

Uno: nunca double para dinero. Ya se dijo en 01-04 y aquí importa más que nunca. Las multas son BigDecimal con precision y scale explícitos:

Dos: Optional no se mapea. Optional<LocalDate> fechaDevolucion era una decisión excelente en 10-04 para la API pública, pero JPA no sabe persistir Optional. La solución es un campo anulable y un getter que devuelva Optional:

Así conservas la garantía de 10-04 —quien llame nunca recibe null— y JPA puede persistir el campo. Es el patrón estándar.

BiblioTech tiene tres enums desde el módulo 4: Gravedad, TipoMaterial y EstadoPrestamo. Su mapeo tiene una trampa con consecuencias graves.

Por qué ORDINAL es peligroso. Con él, la base de datos guarda 0, 1, 2. Ahora imagina que dentro de seis meses alguien añade un estado en su sitio lógico:

Todos los préstamos que estaban guardados con 1 (VENCIDO) pasan a leerse como RENOVADO, y los 2 (DEVUELTO) como VENCIDO. Todos los datos históricos quedan corrompidos silenciosamente. Ninguna excepción, ningún aviso. Se descubre semanas después, cuando alguien reclama una multa de un libro que devolvió.

Además, ORDINAL hace la base de datos ilegible: SELECT * FROM prestamo devuelve números que no significan nada.

La regla es absoluta: @Enumerated(EnumType.STRING), siempre. El ahorro de espacio de ORDINAL no compensa ni de lejos el riesgo. Y lo más peligroso es que ORDINAL es el valor por defecto: si olvidas la anotación, tienes el comportamiento malo.

Buenas noticias: desde JPA 2.2, java.time se mapea de forma nativa. Todo el trabajo de 10-05 se traslada directamente:

La distinción de 10-05 sigue siendo la correcta: LocalDate para fechas de negocio (un préstamo vence "el día 20", sin hora ni zona) e Instant para marcas de tiempo de auditoría (un instante absoluto en la línea temporal).

Y java.util.Date y Calendar no se usan nunca más. Si ves @Temporal(TemporalType.DATE) en un ejemplo, es código anterior a Java 8.

¿Y si quieres persistir un tipo que JPA no conoce? Ahí entra AttributeConverter. BiblioTech tiene un record Isbn como objeto de valor:

El conversor:

Con autoApply = true, cualquier campo Isbn se convierte solo. Sin él, hay que marcarlo:

Esto permite tener objetos de valor con validación en el dominio y columnas simples en la base de datos: lo mejor de los dos mundos. Otros usos habituales: cifrar un campo sensible, guardar una lista corta como cadena separada por comas, o mapear un booleano a 'S'/'N' en una base de datos heredada.

Un embebible es un objeto que no tiene identidad propia y cuyos campos se guardan en la misma fila que la entidad que lo contiene. Sirve para dar estructura al modelo de objetos sin crear tablas.

Uso:

La tabla resultante tiene columnas editorial, anio, idioma, editorial_original, anio_original... en la misma fila de material. No hay tabla datos_publicacion ni JOIN.

Es la respuesta al problema de granularidad del apartado 1: puedes tener objetos pequeños y cohesivos en Java sin fragmentar el esquema.

El modelo de BiblioTech:

• Un Prestamo pertenece a un Material y a un Empleado.
• Un Material tiene muchos Prestamo.
• Un Empleado tiene muchos Prestamo y muchas Reserva.
• Un Material tiene muchas Categoria y una Categoria tiene muchos Material.

La tabla prestamo tendrá columnas material_id y empleado_id con claves foráneas.

Esos métodos de conveniencia no son opcionales en la práctica: si añades a la lista sin poner el campo del otro lado, la relación no se persiste (apartado 13) y además el estado en memoria queda incoherente.

Trampa conocida: un @OneToOne opcional en el lado inverso no puede ser perezoso con proxies, porque Hibernate necesita consultar para saber si hay fila o no. Si el rendimiento importa, ponlo optional = false o usa una clave primaria compartida.

Consejo profesional muy repetido: @ManyToMany puro se queda corto casi siempre. En cuanto necesites un atributo en la relación —fecha en que se asignó la categoría, quién la asignó— hay que convertirla en una entidad intermedia con dos @ManyToOne. Muchos equipos modelan directamente la entidad intermedia desde el principio.

Resumen:

Este es un concepto que confunde a casi todo el mundo y que provoca el bug de "he guardado y no se ha guardado nada".

En una base de datos relacional, la relación es una sola columna: la clave foránea. En Java, la relación bidireccional son dos campos. Alguien tiene que decidir cuál de los dos manda.

El lado propietario es el que tiene la clave foránea. Es el único que Hibernate mira para persistir la relación. El otro lado lleva mappedBy y es de solo lectura a efectos de persistencia.

La consecuencia:

La regla práctica: siempre que tengas una relación bidireccional, escribe métodos de conveniencia que actualicen los dos lados. Nunca manipules las colecciones directamente desde fuera.

Cuando cargas un Prestamo, ¿debe Hibernate cargar también su Material y su Empleado? Esa decisión es FetchType, y es la decisión con más impacto en el rendimiento de toda la lección.

Los valores por defecto de JPA son, desafortunadamente, incoherentes:

Por qué el EAGER por defecto de @ManyToOne es malo: imagina que Prestamo tiene @ManyToOne ansiosos a Material y Empleado, y que Material tiene un @ManyToOne ansioso a Editorial, que tiene otro a Pais. Cargar un préstamo arrastra cinco tablas. Y ese coste lo pagas siempre, incluso cuando solo querías la fecha de vencimiento.

Regla profesional: pon fetch = FetchType.LAZY explícitamente en TODAS las asociaciones. Y cuando necesites los datos relacionados, pídelos explícitamente en la consulta con JOIN FETCH o @EntityGraph.

Cómo funciona un proxy perezoso, y aquí vuelve el módulo 10: cuando cargas un Prestamo, Hibernate no pone un Material en el campo. Pone un objeto de una subclase generada de Material que no tiene datos, solo el id. La primera vez que llamas a material.getTitulo(), esa subclase intercepta la llamada, lanza el SELECT y devuelve el valor.

Es tu proxy dinámico de 10-03 otra vez, y de ahí salen dos consecuencias que ya conoces:

• Una entidad no puede ser final: no se podría generar la subclase.
• Al depurar verás objetos llamados Material$HibernateProxy$xYz123. Es tu material, sin cargar.

La contrapartida de la carga perezosa, y una de las excepciones más famosas del mundo Java.

Qué ha pasado, paso a paso:

1. Dentro de la transacción, Hibernate cargó el préstamo y puso un proxy en el campo material.
2. La transacción terminó y el contexto de persistencia se cerró.
3. Al llamar a getTitulo(), el proxy intenta lanzar el SELECT... y ya no hay sesión con la que hacerlo.

Las soluciones, de mejor a peor:

1. Traer lo que necesitas en la consulta (la correcta):

2. Devolver un DTO en vez de la entidad (la mejor arquitectónicamente):

Ese FichaPrestamo puede ser perfectamente un record — donde sí encajan de maravilla.

3. Ampliar la transacción hasta cubrir el uso: solución válida a veces, pero mantener transacciones abiertas más tiempo del necesario tiene su propio coste.

4. spring.jpa.open-in-view=true: desaconsejada, aunque es el valor por defecto de Spring Boot. Mantiene el contexto de persistencia abierto durante toda la petición HTTP, de modo que la excepción no aparece nunca... y a cambio esconde el problema N+1, mantiene conexiones ocupadas más tiempo y provoca consultas desde la capa de presentación. Por eso en el application.yml del apartado 5 aparece explícitamente:

Consejo: mantenerlo en false hace que la LazyInitializationException aparezca en tu máquina en vez de que el problema de rendimiento aparezca en producción.

El problema de rendimiento número uno de los ORM. Y es tan fácil de provocar que casi todo el mundo lo tiene sin saberlo.

Con 500 préstamos, el log de show-sql muestra:

501 consultas donde debería haber una. Con 2 ms de latencia por consulta, un segundo entero perdido. Y si añades el empleado, son 1001.

Lo insidioso del asunto: en desarrollo, con 5 préstamos de prueba, es instantáneo. El problema aparece en producción con datos reales, y para entonces la causa está en un bucle que parece inofensivo.

Nota importante: cambiar a EAGER no lo arregla. Con EAGER, Hibernate carga las asociaciones siempre, pero muchas veces lo hace igualmente con una consulta por entidad. Lo único que consigues es tener el problema siempre, incluso cuando no ibas a usar los materiales.

Cómo detectarlo:

1. spring.jpa.show-sql=true y contar las consultas en el log.
2. Estadísticas de Hibernate: spring.jpa.properties.hibernate.generate_statistics=true.
3. En producción: métricas y trazas distribuidas (12-07).

Dos soluciones, ambas de la especificación.

Ahora se genera una sola consulta:

De 501 consultas a 1.

Ojo con un detalle: JOIN FETCH sobre una colección puede duplicar filas. Si traes un empleado con sus 5 préstamos, el JOIN devuelve 5 filas y podrías obtener el empleado repetido. Se resuelve con SELECT DISTINCT o pidiendo un Set. Y una limitación conocida: no se puede paginar un JOIN FETCH de colección de forma eficiente; Hibernate avisa de que está paginando en memoria. En ese caso, la solución es traer los ids paginados en una consulta y las entidades completas en otra.

Ventaja: el mismo método puede tener varios grafos, y no hay que escribir JPQL.

La proyección a DTO merece mención aparte porque es la solución más eficiente para informes:

Una consulta, solo cuatro columnas, sin entidades gestionadas y sin riesgo de N+1. Y FichaPrestamo es un record — que por fin encuentra su sitio en la capa de persistencia.

Las cascadas propagan operaciones del padre a los hijos.

orphanRemoval = true significa: si quitas un hijo de la colección, bórralo de la base de datos.

Diferencia con CascadeType.REMOVE:

Aviso serio: CascadeType.ALL sobre relaciones donde el hijo tiene vida propia es una fuente de pérdida de datos. Si Material tuviera cascade = ALL sobre sus préstamos, dar de baja un libro borraría todo su historial de préstamos, con sus multas y su auditoría. Usa cascadas solo cuando la relación sea de composición real (el hijo no existe sin el padre).

Aquí está el corazón conceptual de JPA, y lo que separa a quien entiende Hibernate de quien lo sufre.

El EntityManager es la puerta de entrada a JPA. Y gestiona un contexto de persistencia: una caché de entidades donde cada entidad cargada o guardada queda gestionada mientras dure la transacción.

Tres propiedades del contexto de persistencia, todas con consecuencias:

1. Es una caché de primer nivel. Si pides dos veces la misma entidad en la misma transacción, la segunda no genera consulta.
2. Garantiza identidad. Dentro de una transacción, la misma fila es siempre el mismo objeto Java: a == b es true. Eso resuelve el problema de identidad del apartado 1.
3. Detecta cambios automáticamente. Es el apartado 21, y es lo que más sorprende.

En Spring, el EntityManager se inyecta así:

Ese EntityManager inyectado no es una instancia real: es un proxy que en cada llamada busca el contexto de persistencia asociado a la transacción del hilo actual. Otra vez el mismo mecanismo del módulo 10.

Toda entidad está en uno de cuatro estados, y saber en cuál es la clave para entender qué va a hacer Hibernate.

El ejemplo que lo aclara todo:

Y el error clásico que produce:

Para que un cambio sobre una entidad separada se guarde, hay que reincorporarla con merge (apartado 23).

Esto es lo que más sorprende de JPA, y a la vez lo más potente.

¿Cómo? El mecanismo se llama dirty checking y funciona así:

1. Al cargar la entidad, Hibernate guarda una instantánea del estado de todos sus campos.
2. Al hacer flush (normalmente al confirmar), compara el estado actual con la instantánea.
3. Para cada campo distinto, genera el UPDATE correspondiente.

Consecuencias prácticas, todas importantes:

Uno: no hace falta llamar a save sobre entidades gestionadas. Muchísimo código Spring Data llama a save() innecesariamente. No hace daño, pero es ruido.

Dos: cualquier modificación accidental se persiste. Si dentro de una transacción tocas un campo de una entidad gestionada "solo para calcular algo", ese cambio va a la base de datos. Es una fuente real de bugs desconcertantes.

Tres: readOnly = true lo desactiva y ahorra trabajo.

En consultas que devuelven muchas entidades, la diferencia es medible. Es una buena costumbre marcar readOnly = true en todos los métodos de solo lectura.

Cuatro: el coste crece con el número de entidades gestionadas. Cargar 100.000 entidades en una transacción hace que cada flush compare 100.000 instantáneas. Para procesos masivos hay que limpiar el contexto periódicamente con entityManager.clear().

flush es el momento en que Hibernate escribe realmente el SQL pendiente en la base de datos. No es lo mismo que commit.

Cuándo ocurre automáticamente:

1. Al confirmar la transacción (siempre).
2. Antes de ejecutar una consulta que pudiera verse afectada por los cambios pendientes.
3. Cuando llamas a entityManager.flush() explícitamente.

Y aquí viene un detalle que sorprende: Hibernate no ejecuta el SQL en el orden en que tú llamas a los métodos. Reordena las operaciones así:

1. INSERT de entidades, en orden de persist
2. UPDATE
3. Borrado de elementos de colecciones
4. Inserción de elementos de colecciones
5. DELETE de entidades

Por eso este código puede fallar de forma incomprensible:

La solución es forzar el orden:

Entender que existe un "SQL pendiente" que se ejecuta más tarde y reordenado explica la mitad de los comportamientos raros de Hibernate.

La regla: usa siempre el objeto que devuelve merge. Ignorar el valor de retorno es un error frecuentísimo.

Lo único que necesita el INSERT es el material_id, y getReference lo tiene. Ahorras un SELECT por operación. La contrapartida: si accedes a cualquier propiedad del proxy fuera de la sesión, tendrás una LazyInitializationException, y si el id no existe, el error llega tarde (EntityNotFoundException al acceder, no al pedir la referencia).

JPQL (Jakarta Persistence Query Language) parece SQL pero opera sobre entidades y sus atributos Java, no sobre tablas y columnas.

Ejemplos completos sobre BiblioTech:

Aviso sobre esa última: las consultas de modificación masiva se ejecutan directamente en la base de datos y no actualizan las entidades ya cargadas en el contexto de persistencia, que quedan desincronizadas. Después de una así, conviene em.clear().

Diferencias clave con SQL:

Se declaran en la entidad y se validan al arrancar, no al ejecutarse:

Ventaja real: un error de sintaxis en el JPQL impide arrancar la aplicación, en vez de estallar el día que alguien invoque ese informe.

Para consultas construidas dinámicamente —un buscador con cinco filtros opcionales—, concatenar JPQL a mano es feo y peligroso. JPA ofrece una API con tipos:

Es verbosa, y por eso mucha gente prefiere las Specification de Spring Data o QueryDSL. Se menciona para que sepas que existe y para qué sirve; en la práctica se usa poco.

Cuando necesitas una función específica del motor, una consulta muy optimizada o un informe complejo:

Es perfectamente legítimo. Un ORM no obliga a hacerlo todo con él, y pretender lo contrario lleva a JPQL retorcidos que nadie entiende. La única pérdida es la portabilidad entre motores.

Esto no es una recomendación de estilo. Es una vulnerabilidad de seguridad.

Si correo viene de un formulario o de un parámetro de una API, un atacante puede enviar:

Y la consulta se convierte en:

que devuelve todos los préstamos de todos los empleados. Con SQL nativo, las consecuencias son peores: dependiendo del motor y de los permisos, se puede llegar a leer otras tablas o modificar datos.

La solución es siempre la misma, y es trivial:

Con parámetros, el valor nunca se interpreta como parte de la consulta: viaja aparte y se trata como un dato literal, pase lo que pase dentro. Es la misma razón por la que el ejemplo de JDBC del apartado 3 usaba PreparedStatement con ? y setString.

La regla, sin excepciones: todo valor que venga de fuera va como parámetro. Ni siquiera "cuando sé que es un número" —porque mañana ese código se copia a otro sitio donde no lo es.

Lo único que no se puede parametrizar son los nombres de tabla y columna y el sentido de un ORDER BY. Si necesitas que sean dinámicos, valídalos contra una lista blanca de valores permitidos, nunca los concatenes tal cual.

La seguridad de aplicaciones —validación de entrada, autorización, gestión de secretos, cabeceras— se trata en 12-07. Aquí basta con la regla: parámetros siempre.

Ahora que hay base de datos, el @Transactional de 11-02 hace algo.

Una transacción cumple las propiedades ACID:

El caso de BiblioTech:

Si registroAuditoria.anotar falla, se revierte todo: el ejemplar vuelve a estar disponible y no queda ningún préstamo huérfano. Sin transacción, quedaría un ejemplar menos y un préstamo sin auditar, y nadie sabría por qué.

Recuerda las dos reglas de 11-02, que siguen valiendo aquí: rollback solo ante excepciones no comprobadas por defecto, y las llamadas internas no pasan por el proxy.

El caso donde REQUIRES_NEW es la respuesta correcta:

Cuidado: REQUIRES_NEW consume una segunda conexión del pool mientras la primera sigue abierta. Abusar de él agota el pool y provoca interbloqueos. Úsalo solo cuando la independencia sea un requisito real.

Los tres fenómenos, con BiblioTech:

• Lectura sucia: lees un ejemplar como prestado y esa transacción se revierte. Leíste algo que nunca existió.
• Lectura no repetible: lees ejemplares_disponibles = 1, otro presta, vuelves a leer y hay 0. Dos lecturas, dos resultados.
• Lectura fantasma: cuentas 3 préstamos activos, otro inserta uno, repites la consulta y hay 4.

En la práctica, casi nunca se toca el aislamiento. READ_COMMITTED con bloqueo optimista (siguiente apartado) resuelve el 99 % de los casos con mucho menos coste que subir el nivel.

El caso concreto, que retoma directamente el módulo 8:

Marta Ruiz y Diego Alonso abren a la vez la ficha de "Java Efectivo", que tiene 1 ejemplar disponible. Los dos pulsan "Prestar" en el mismo segundo.

Es exactamente la condición de carrera de 08-04, pero distribuida: aquí synchronized no sirve de nada, porque los dos usuarios pueden estar en instancias distintas de la aplicación.

Dos estrategias:

El bloqueo optimista es una sola anotación:

Con eso, cada UPDATE incluye la versión leída en la condición:

Si otro ya actualizó, la fila tiene version=6 y la condición no encuentra ninguna fila. Hibernate lo detecta y lanza:

Manejarlo bien:

Ese Resultado<T> es el tipo genérico que escribiste en 10-01, y aquí encaja perfectamente. Y ese bucle de reintentos es, conceptualmente, tu ProxyReintentos de 10-03: en un proyecto real lo declararías con @Retryable de Spring Retry.

Bloqueo pesimista, cuando la operación es cara y el conflicto probable:

Genera SELECT ... FOR UPDATE: el segundo espera al primero. Correcto, pero con coste real de concurrencia.

La de primer nivel ya la conoces: es el contexto de persistencia del apartado 19. No se puede desactivar y es la que garantiza la identidad de objetos.

La de segundo nivel es opcional y compartida por todas las transacciones. Necesita un proveedor (Ehcache, Caffeine, Hazelcast):

Cuándo activarla: datos que se leen mucho y cambian poco. El catálogo de materiales o las categorías de BiblioTech son buenos candidatos; los préstamos, no.

Advertencias que hay que tener presentes:

1. Coherencia: si otra aplicación modifica la base de datos, tu caché queda obsoleta y sirve datos viejos.
2. En clúster: con varias instancias, cada una tiene su caché. O usas una caché distribuida o tendrás incoherencias.
3. Mide antes: activar la caché de segundo nivel "por si acaso" añade complejidad sin beneficio demostrado. Es exactamente lo que 10-07 decía: medir antes de optimizar.

Hibernate puede generar el esquema a partir de tus entidades. Es cómodo y peligroso.

Por qué update no se usa nunca en producción, con motivos concretos:

1. Nunca borra nada. Si quitas un campo, la columna se queda ahí para siempre. Si renombras titulo a nombre, añade nombre y deja titulo — y no copia los datos.
2. No versiona nada. No hay registro de qué cambios se aplicaron ni cuándo, y no hay forma de deshacerlos.
3. Es impredecible. El SQL que genera depende del dialecto, de la versión de Hibernate y del estado actual del esquema.
4. No se puede revisar antes. Nadie ha visto el ALTER TABLE que va a ejecutarse contra la base de datos de producción.
5. No puede hacer migraciones de datos. Dividir nombre_completo en nombre y apellidos requiere lógica que ninguna herramienta automática puede inventar.

La configuración correcta por entorno:

validate es especialmente valioso: si el esquema real no coincide con las entidades, la aplicación no arranca, y eso es mucho mejor que descubrirlo con un error a las tres de la mañana.

En producción, el esquema se gestiona con migraciones versionadas: ficheros SQL numerados que se aplican en orden y quedan registrados en una tabla de control.

Ventajas: el cambio de esquema está en git, es revisable, es reproducible y se puede probar antes. Se desarrolla en 12-06, junto con el despliegue.

Última pieza, y la que más código elimina.

Con JPA puro, un repositorio son unas ochenta líneas. Con Spring Data JPA:

Eso ya te da save, findById, findAll, deleteById, count, existsById, paginación y ordenación.

Spring Data analiza el nombre del método y genera la consulta. Las palabras clave habituales:

Consejo práctico: los nombres derivados son fantásticos hasta que dejan de serlo. findByFechaVencimientoBeforeAndFechaDevolucionIsNullAndEstadoNot es ilegible. Cuando el nombre pase de tres condiciones, usa @Query.

Si no necesitas el total, Slice<T> evita el COUNT y es más rápido.

PrestamoRepository es una interfaz sin implementación. ¿Quién ejecuta findByEstado?

En el arranque, Spring Data:

1. Escanea las interfaces que extienden Repository.
2. Para cada una, crea una implementación al vuelo con Proxy.newProxyInstance — el mismo de 10-03.
3. El InvocationHandler recibe cada llamada, mira si el método tiene @Query (y usa ese JPQL) o analiza su nombre (y genera el JPQL), lo ejecuta con el EntityManager y adapta el resultado.

Es literalmente lo que escribiste en 10-03: un proxy sobre una interfaz que interpreta los metadatos del método y actúa. La diferencia es la sofisticación del análisis, no el mecanismo.

Y hay una consecuencia práctica: el repositorio se puede sustituir por un simulado en las pruebas sin ninguna dificultad, porque es una interfaz. Es exactamente lo que hará 11-06.

El resultado completo de la migración.

Aquí se paga uno de los precios reales del ORM, y hay que decirlo con claridad: la jerarquía sealed de 10-06 desaparece. Una entidad JPA no puede ser sealed ni record ni final. Se pierden los switch exhaustivos verificados por el compilador y hay que sustituirlos por polimorfismo o por comprobaciones con instanceof. Es un compromiso consciente: se gana persistencia real, consultas e integridad; se pierde parte de la expresividad del modelo de tipos. Un diseño alternativo —y frecuente en proyectos que valoran mucho el dominio— mantiene el dominio puro y usa entidades JPA separadas con un mapeo entre ambos. Esa discusión pertenece a 12-02.

Las tres estrategias de herencia, para que sepas qué elegiste:

Los repositorios:

Datos iniciales para desarrollo, en src/main/resources/data.sql:

Ejecución:

El antes y el después:

Error: javax.persistence en vez de jakarta.persistence. El error de copia y pega número uno hoy. Spring Boot 3 y Hibernate 6 usan jakarta.

Error: dejar @Enumerated por defecto (ORDINAL). Reordenar un enum corrompe silenciosamente todos los datos históricos. Siempre EnumType.STRING.

Error: dejar @ManyToOne en EAGER. Es el valor por defecto y es malo. Pon LAZY explícitamente en todas las asociaciones y trae lo que necesites con JOIN FETCH.

Error: el problema N+1 sin darse cuenta. Un bucle sobre entidades accediendo a una relación perezosa. Activa show-sql en desarrollo y cuenta las consultas.

Error: spring.jpa.open-in-view=true. Es el valor por defecto de Spring Boot y esconde el N+1 hasta producción. Ponlo a false.

Error: modificar solo el lado inverso de una relación. empleado.getPrestamos().add(p) sin p.setEmpleado(empleado) no persiste nada. Escribe métodos de conveniencia.

Error: ignorar el retorno de merge. merge(e) devuelve otra instancia; la original sigue separada y sus cambios se pierden.

Error: CascadeType.ALL sin pensarlo. Borrar un material podría borrar su historial completo de préstamos.

Error: ddl-auto=update en producción. No borra, no versiona, no migra datos y nadie revisa el SQL que va a ejecutar. validate más Flyway.

Error: concatenar valores en una consulta. Es inyección SQL. Parámetros siempre, sin excepciones.

Error: entidades final, record o con métodos final. Hibernate necesita generar subclases proxy. No compilará el modelo o fallará la carga perezosa.

Error: equals y hashCode basados en el id generado. Antes de persistir, el id es null; después cambia, y una entidad metida en un HashSet deja de encontrarse. Usa una clave de negocio (el isbn) o el patrón recomendado de Hibernate.

Consejo: activa show-sql mientras aprendes. Ver el SQL generado es la mitad del aprendizaje, y te enseña a detectar el N+1 al instante.

Consejo: marca readOnly = true en los métodos de consulta. Desactiva la comprobación de cambios y ahorra trabajo real.

Consejo: usa DTO (record) para lo que sale del servicio. Devolver entidades gestionadas fuera de la transacción es la causa directa de la LazyInitializationException, y además acopla tu API interna al esquema.

Consejo: @Version en toda entidad que se modifique concurrentemente. Cuesta una anotación y evita actualizaciones perdidas.

Consejo: no lo hagas todo con el ORM. Para informes y agregaciones, SQL nativo o JdbcTemplate son mejores herramientas. Es legítimo y profesional.

Consejo: getReference cuando solo necesites la referencia para asignar una FK. Ahorra un SELECT por operación.

BiblioTech tiene reservas: cuando no hay ejemplares, un empleado reserva y se le avisa al devolverse uno. Este es el record del módulo 10:

Conviértelo en una entidad JPA que cumpla:

1. Tabla reserva con clave primaria autogenerada.
2. Relaciones @ManyToOne perezosas a Material y Empleado, no cadenas.
3. El enum guardado de forma segura.
4. instanteAviso anulable en la base de datos pero expuesto como Optional.
5. Bloqueo optimista.
6. Un índice sobre (material_id, estado) para la consulta de pendientes.
7. Un método de dominio avisar(Clock reloj) que cambie el estado y registre el instante, con validación.
8. El repositorio Spring Data con: pendientes de un material ordenadas por antigüedad, caducadas antes de una fecha, y contar pendientes de un empleado.

Este servicio funciona bien con los 5 préstamos de desarrollo y tarda 9 segundos en producción con 800.

Se pide:

1. Calcula cuántas consultas SQL se ejecutan con 800 préstamos, desglosadas.
2. Explica exactamente por qué.
3. Propón tres soluciones distintas con su código, indicando cuántas consultas quedan en cada una.
4. Di cuál elegirías y por qué.

Marta Ruiz y Diego Alonso intentan prestar simultáneamente el último ejemplar de "Refactorización" (978-0000000003, 1 ejemplar).

Se pide:

1. Describe la secuencia exacta de eventos que produce dos préstamos con un solo ejemplar.
2. Explica por qué synchronized (08-04) no resuelve esto en un despliegue real.
3. Resuélvelo con bloqueo optimista, incluyendo el manejo de la excepción con reintento.
4. Resuélvelo con bloqueo pesimista.
5. Compara ambas en una tabla y recomienda una.

Solución 1

Repositorio (8):

Decisiones destacables:

• record → clase: obligatorio, porque un record es final y sin constructor vacío.
• Relaciones en vez de cadenas: Material y Empleado en vez de isbn y correoEmpleado. Da integridad referencial (no se puede reservar un material inexistente) y navegación. El precio es tener que gestionar la pereza.
• Optional fuera, campo anulable dentro: se conserva la garantía de 10-04 sin pelearse con JPA.
• El comportamiento vive en la entidad: avisar, completar y haCaducado validan las transiciones. La entidad no es una bolsa de datos.
• @EntityGraph en la primera consulta: se sabe que se va a leer el nombre del empleado, así que se trae de una vez.

Solución 2

1. Cuántas consultas.

Con 3-4 ms de latencia por consulta, entre 7 y 10 segundos. Coincide con el síntoma.

2. Por qué. Las tres asociaciones son perezosas. La consulta inicial trae solo las filas de prestamo, con proxies en material y empleado y una colección perezosa en categorias. Cada acceso dentro del map dispara su propio SELECT. En desarrollo, con 5 préstamos, son 16 consultas y nadie lo nota.

Solución A — JOIN FETCH (1 consulta si se limita a lo escalar, 2 con la colección):

DISTINCT es necesario porque el JOIN FETCH de la colección de categorías duplica filas de préstamo. 1 consulta. Limitación: no se puede paginar eficientemente con un JOIN FETCH de colección.

Solución B — @EntityGraph (declarativa, mismo resultado):

Ventaja: no se toca el código del servicio y el mismo método puede tener otro grafo en otra consulta. 1-2 consultas.

Solución C — proyección a DTO (la más eficiente):

1 consulta, y solo 3 columnas en vez de todas las de tres tablas. Sin entidades gestionadas, sin comprobación de cambios, sin riesgo de N+1 posterior. Para las categorías haría falta una consulta adicional o STRING_AGG en SQL nativo.

Comparación:

4. Cuál elegir. Para un informe de solo lectura, la C. Razones: trae solo lo necesario, no hay entidades gestionadas ni comprobación de cambios, y —lo más importante— es estructuralmente imposible que reaparezca el N+1, porque no hay proxies que puedan dispararse. Con A y B, alguien que mañana añada un p.getMaterial().getEditorial().getPais() al formato vuelve a tener el problema.

Si el método tuviera que devolver entidades para modificarlas después, la B, por ser declarativa y reutilizable.

Solución 3

1. La secuencia.

Es una actualización perdida: el UPDATE de Diego se calculó a partir de un valor obsoleto. Con READ_COMMITTED, ninguna de las dos transacciones ve nada anómalo.

2. Por qué synchronized no sirve. synchronized sincroniza hilos dentro de una misma JVM. En un despliegue real hay varias instancias de BiblioTech tras un balanceador (12-06), y Marta y Diego pueden estar atendidos por procesos distintos, en máquinas distintas. Un monitor de la JVM A no bloquea nada en la JVM B. Además, aunque hubiera una sola instancia, serializar todos los préstamos de todos los materiales por un único cerrojo sería un cuello de botella innecesario. La coordinación tiene que estar donde está el dato compartido: en la base de datos.

3. Bloqueo optimista.

Qué pasa ahora en t8: el UPDATE de Diego lleva where id=1 and version=0, pero la fila ya tiene version=1. Afecta a 0 filas, Hibernate lanza OptimisticLockException y Spring la traduce a OptimisticLockingFailureException. El reintento vuelve a leer, ve disponibles=0 y devuelve un error de negocio correcto.

Resultado<T> es el tipo genérico de 10-01, y el bucle de reintentos es tu ProxyReintentos de 10-03 — que en un proyecto real sería @Retryable(retryFor = OptimisticLockingFailureException.class, maxAttempts = 3).

4. Bloqueo pesimista.

Conviene añadir un tiempo máximo de espera para no bloquear indefinidamente:

5. Comparación y recomendación.

Recomendación: bloqueo optimista. En BiblioTech, la probabilidad de que dos personas presten el mismo ejemplar en el mismo segundo es bajísima, y el bloqueo pesimista haría pagar el coste de la serialización a las miles de operaciones que nunca chocan. @Version cuesta una anotación, no penaliza el caso normal y funciona igual con una instancia que con veinte.

El bloqueo pesimista se reserva para operaciones donde el conflicto sea la norma y el trabajo perdido sea caro: por ejemplo, un proceso nocturno que recalcula todas las multas y no quiere reintentar cinco mil veces.

Los CSV de BiblioTech han desaparecido. Hay una base de datos de verdad debajo, y sabes exactamente qué está pasando en ella.

Entiendes el desajuste objeto-relacional que un ORM existe para gestionar: identidad doble, herencia que en SQL no existe, navegación que en Java es gratis y en SQL cuesta consultas, granularidad, colecciones y tipos. Y sabes qué ganas y qué pierdes frente a JDBC directo —que viste en veinte líneas, con su mapeo columna a columna, su conversión de tipos y su gestión de recursos— con la regla profesional que se deriva: ORM para el CRUD del dominio, SQL directo para informes y procesos masivos, y ambos conviviendo sin conflicto.

Distingues JPA de Hibernate: especificación (jakarta.persistence) frente a implementación, con la recomendación de programar contra la especificación y la advertencia de versiones que hoy causa más errores de compilación que ninguna otra —jakarta, nunca javax.

Sabes mapear entidades: @Entity, @Table, @Id, las estrategias de @GeneratedValue con el motivo real por el que SEQUENCE supera a IDENTITY (permite agrupar inserciones), @Column con sus atributos, y los requisitos que impone JPA —constructor sin argumentos, nada final— que explican por qué un record no puede ser una entidad. Conoces la regla absoluta de @Enumerated(EnumType.STRING), porque ORDINAL es el valor por defecto y reordenar un enum corrompe silenciosamente todos los datos históricos. Mapeas LocalDate e Instant de forma nativa con la misma distinción de 10-05, escribes conversores con AttributeConverter para objetos de valor como Isbn, y usas @Embeddable para tener objetos pequeños en Java sin fragmentar el esquema.

Modelas relaciones completas con sus cuatro tipos, sabes que el lado propietario es el que tiene la clave foránea y que tocar solo el lado inverso no persiste nada —de ahí los métodos de conveniencia—, y dominas la decisión que más impacto tiene en el rendimiento: FetchType. Sabes que los valores por defecto son incoherentes, que @ManyToOne viene en EAGER y que la regla profesional es poner LAZY explícitamente en todo y pedir lo que necesites en la consulta. Conoces las dos consecuencias: la LazyInitializationException, con sus cuatro soluciones ordenadas y el consejo de dejar open-in-view en false para que el problema aparezca en tu máquina y no en producción; y el problema N+1, que convierte una consulta en 501 y que es invisible con cinco filas de prueba, con sus soluciones —JOIN FETCH, @EntityGraph, @BatchSize y, la más eficiente para informes, la proyección a DTO, donde los record encuentran por fin su sitio—. Y sabes que pasar a EAGER no arregla nada: lo empeora.

Entiendes el contexto de persistencia, que es el corazón conceptual de JPA: una caché de primer nivel que garantiza que la misma fila es el mismo objeto, con los cuatro estados de una entidad y sus transiciones. Y con ello la comprobación de cambios automática, que sorprende a todo el mundo: modificas una entidad gestionada, no llamas a nada, y al confirmar aparece un UPDATE. Sabes cómo funciona (instantánea y comparación), sus cuatro consecuencias —incluido que un cambio accidental se persiste— y por qué readOnly = true la desactiva y ahorra trabajo real. Conoces flush, que reordena las operaciones y explica la mitad de los comportamientos raros de Hibernate, y la diferencia entre persist y merge que provoca el bug de "ignoré el valor de retorno".

Escribes consultas: JPQL sobre entidades y atributos, consultas con nombre validadas en el arranque, la API de criterios para lo dinámico, SQL nativo cuando toca, y proyecciones a record en una sola línea. Y tienes interiorizada la regla que no admite excepciones: todo valor externo va como parámetro, porque concatenar es inyección SQL —con la lista blanca como única salida cuando lo dinámico es un nombre de columna—.

Manejas transacciones con base de datos real: ACID, @Transactional con sus dos reglas heredadas de 11-02, readOnly, propagación con el caso legítimo de REQUIRES_NEW y su coste en conexiones, y aislamiento con los tres fenómenos explicados sobre BiblioTech y el consejo de casi nunca tocarlo. Y resuelves el caso del ejemplar disputado con bloqueo optimista con @Version, entendiendo por qué synchronized del módulo 8 no sirve cuando hay varias instancias: la coordinación tiene que estar donde está el dato compartido. Con reintento sobre Resultado<T>, que es tu genérico de 10-01 y tu ProxyReintentos de 10-03 hechos producción.

Conoces las cachés de primer y segundo nivel y cuándo la segunda merece la pena —datos que se leen mucho y cambian poco, medido antes—; y sabes por qué ddl-auto=update no se usa nunca en producción: no borra, no versiona, no migra datos y nadie revisa el ALTER TABLE que va a ejecutar. validate más migraciones versionadas con Flyway, que llegan en 12-06.

Y has visto Spring Data JPA convertir ochenta líneas de repositorio en una interfaz vacía, con métodos derivados del nombre, @Query para lo que no cabe en un nombre, y paginación. Con el mecanismo al descubierto: Proxy.newProxyInstance sobre una interfaz, exactamente el de 10-03, analizando metadatos del método y generando la consulta.

BiblioTech tiene ahora entidades reales, relaciones con integridad referencial, transacciones ACID, bloqueo optimista y consultas con índices sobre H2. Arranca con mvn spring-boot:run y su esquema se crea solo.

Y sigue sin tener ni una sola prueba automática.

Esa es ahora, con diferencia, la deuda más grave. Acabas de hacer una migración enorme: has cambiado el modelo de dominio, has convertido record en clases, has sustituido la persistencia entera y has introducido concurrencia optimista con reintentos. ¿Cómo sabes que el cálculo de multas sigue dando el mismo resultado? ¿Que el límite de tres préstamos por empleado se sigue respetando? ¿Que un préstamo que vence en domingo sigue avisando el lunes? La única respuesta honesta hoy es: arrancando la aplicación y mirando.

Y hay algo peor. Ese Clock inyectable que introdujiste en 10-05, que pasó por Spring en 11-02 como un @Bean y que en esta lección ha aparecido en cada LocalDate.now(reloj) y cada Instant.now(reloj), existe exclusivamente para poder probar el código sin esperar quince días. Lleva dos módulos esperando a que alguien lo aproveche.

En la próxima lección se aprovecha. Verás qué es una prueba automática y por qué el coste de no tenerlas ya lo estás pagando; conocerás la pirámide de pruebas y JUnit 5 completo, desde @Test y el patrón Preparar-Actuar-Comprobar hasta las pruebas parametrizadas que verifican doce casos del cálculo de multas en seis líneas; compararás las aserciones de JUnit con las de AssertJ; y descubrirás qué hace que un diseño sea testeable — y por qué todo lo que has hecho en los dos últimos módulos (inyección por constructor, interfaces en las fronteras, el Clock inyectado, el dominio libre de anotaciones) apuntaba exactamente ahí.

BiblioTech va a tener su primera red de seguridad.