JPA en Producción: Relaciones, N+1, Paginación y Migraciones

En una relación entre tablas, la clave foránea vive en una sola de ellas: lineas_pedido.pedido_id. En JPA, la entidad que tiene esa columna es el lado propietario y se mapea con @ManyToOne (y @JoinColumn). El otro lado, Pedido.lineas con @OneToMany(mappedBy = "pedido"), es opcional y solo sirve para navegar: Hibernate lo ignora al decidir qué escribir.

En las relaciones bidireccionales tienes que mantener los dos lados coherentes en memoria. Lo habitual es encapsular la colección y ofrecer métodos addLinea y removeLinea que actualizan la lista y el campo pedido a la vez. cascade = CascadeType.ALL propaga persist y remove del padre a los hijos, y orphanRemoval = true borra una línea cuando la quitas de la colección.

No todas las relaciones necesitan ser bidireccionales. Un @ManyToOne unidireccional suele bastar; la colección @OneToMany solo merece la pena cuando el padre controla el ciclo de vida de los hijos (un pedido y sus líneas), no para relaciones con miles de elementos (un cliente y todos sus pedidos).

Una relación LAZY se rellena con un proxy (en @ManyToOne) o con una colección persistente sin inicializar (en @OneToMany). La consulta real se lanza la primera vez que accedes a sus datos, siempre que la sesión de Hibernate siga abierta; si ya se cerró, obtienes LazyInitializationException.

El N+1 surge al combinar una lista con ese acceso perezoso. findAll() trae 200 pedidos en una consulta, y el bucle que pinta pedido.getCliente().getNombre() dispara una consulta por cada cliente. Lo mismo ocurre al serializar a JSON una entidad con relaciones. Los valores por defecto empeoran el problema: @ManyToOne y @OneToOne son EAGER, y al cargar 200 pedidos con una consulta JPQL, Hibernate lanza después las consultas de sus clientes de todas formas.

Para verlo, activa los logs de SQL en desarrollo (logging.level.org.hibernate.SQL=DEBUG) o las estadísticas de Hibernate (hibernate.generate_statistics=true), que cuentan las consultas por sesión. Un test que fija el número de consultas evita que el problema vuelva.

JOIN FETCH le dice a Hibernate que traiga la relación en la misma consulta y rellene con ella la entidad: select p from Pedido p join fetch p.cliente. Con @EntityGraph(attributePaths = {"cliente"}) sobre un método de Spring Data obtienes el mismo resultado sin escribir JPQL, y puedes seguir usando métodos derivados (findByEstado).

Con colecciones hay que tener cuidado. Un JOIN FETCH de lineas repite el pedido en cada fila de línea; Hibernate 6 vuelve a agrupar las entidades raíz, así que ya no hace falta DISTINCT. Pero dos colecciones a la vez producen el producto cartesiano de ambas y, si son List, Hibernate lanza MultipleBagFetchException. En ese caso se cargan en consultas separadas o con @BatchSize, que carga las colecciones de varios padres a la vez con un IN (...).

Cuando la pantalla solo necesita unos campos, la opción más eficiente es una proyección: una consulta que construye directamente un DTO (select new com.app.ResumenPedido(p.id, c.nombre) from Pedido p join p.cliente c). No crea entidades gestionadas, no tiene relaciones que cargar y trae solo las columnas necesarias.

Spring Data acepta un parámetro Pageable en cualquier método de repositorio y lo traduce a LIMIT y OFFSET con el orden indicado. Si el método devuelve Page<T>, lanza además una consulta count para saber el total de elementos y de páginas; si devuelve Slice<T>, pide un elemento de más para saber si hay página siguiente y se ahorra el recuento, que en tablas grandes puede ser lo más caro.

En un controlador, Spring convierte automáticamente los parámetros ?page=0&size=20&sort=creada,desc en un Pageable. Conviene limitar el tamaño máximo (spring.data.web.pageable.max-page-size) para que nadie pida un millón de filas, y devolver DTO en lugar de entidades. Desde Spring Data 3.3, para serializar una página a JSON se recomienda PagedModel, que da un formato estable.

OFFSET tiene un límite: para llegar a la página 10.000, la base de datos recorre y descarta todas las filas anteriores. En listados muy profundos o feeds infinitos se usa paginación por cursor (keyset): where creada < :ultimaVista order by creada desc limit 20, que aprovecha el índice y tarda lo mismo en cualquier página.

Flyway busca scripts en classpath:db/migration con el formato V<versión>__<descripción>.sql, los ordena por versión y aplica los que faltan, cada uno en su transacción cuando la base de datos lo permite. En la tabla flyway_schema_history guarda la versión, la fecha y un checksum de cada script aplicado. Spring Boot ejecuta Flyway al arrancar, antes de inicializar JPA, así que Hibernate siempre ve el esquema actualizado.

Con spring.jpa.hibernate.ddl-auto=validate, Hibernate comprueba al arrancar que las entidades coinciden con las tablas y falla si no. Juntos dan un esquema que solo cambia mediante migraciones revisadas y un aviso inmediato si el código y el esquema se desalinean.

Las migraciones aplicadas son inmutables: cambiar un script ya ejecutado altera su checksum y la validación falla. Los cambios se escriben siempre en una migración nueva. Los cambios que rompen la compatibilidad (renombrar una columna con la aplicación en marcha) se hacen en varios pasos: añadir la columna nueva, copiar los datos y desplegar código que use las dos, y borrar la antigua en una versión posterior.