La lección anterior cerró el módulo 3 con una constatación incómoda: la API de CicloUrbana está completa, documentada y publicable, pero cuando el proceso se reinicia todo desaparece. Las cuatro estaciones de Ribalta vuelven a nacer del CargadorEstacionesDemo, las bicicletas dadas de alta se esfuman y los alquileres del día se pierden. Todo vive en el ConcurrentHashMap de EstacionRepositorioEnMemoria, que existe mientras existe la JVM. Este módulo sustituye esa provisionalidad por persistencia real sobre una base de datos relacional, y lo hace sin tocar ni un controlador, gracias a que desde 02-01 escondimos el almacenamiento tras la interfaz EstacionRepositorio.

Antes de escribir una sola anotación conviene entender el terreno. Esta lección es conceptual y responde a las preguntas que casi nadie se hace antes de empezar y todo el mundo se hace cuando algo falla: por qué existe un ORM, qué significa exactamente cada una de las cuatro siglas que se mezclan a diario —JDBC, JPA, Hibernate, Spring Data JPA—, qué es el contexto de persistencia y por qué una entidad puede estar «gestionada» o «separada», y qué hace Spring Boot por su cuenta en cuanto detecta el starter. Sin esta base, JPA parece magia; con ella, es una máquina previsible.

1. El desfase objeto-relacional
2. Qué es un ORM y qué problema resuelve realmente
3. Quién es quién: JDBC, JPA, Hibernate y Spring Data JPA
4. Qué aporta spring-boot-starter-data-jpa
5. EntityManager, unidad de persistencia y contexto de persistencia
6. Los cuatro estados de una entidad
7. Qué genera Spring Boot al detectar el starter
8. Alternativas a JPA en el ecosistema Spring
9. El modelo de datos objetivo de CicloUrbana
10. Errores Comunes y Consejos
11. Ejercicios

En Java, Estacion es un objeto: tiene identidad propia (dos objetos distintos aunque sean iguales campo a campo), referencias directas a otros objetos, herencia, y vive en un grafo que el recolector de basura gestiona. En una base de datos relacional, una estación es una fila en una tabla: tiene identidad por clave primaria, se relaciona con otras filas mediante claves ajenas, no hereda de nada y solo existe dentro de un conjunto de tuplas.

Los dos modelos son buenos, pero no encajan. A esa colección de desencuentros se le llama desfase objeto-relacional (object-relational impedance mismatch), y tiene cinco caras concretas:

Un ejemplo de CicloUrbana lo hace tangible. Para obtener el nombre de la estación de una bicicleta, en Java lo natural es:

En SQL lo natural es lo contrario: pedirlo todo de golpe.

La primera forma, ejecutada dentro de un bucle sobre cien bicicletas, produce cien consultas. Ese es el germen del problema N+1 que veremos en 04-04. No es un fallo de JPA: es el desfase asomando.

Un ORM (Object-Relational Mapping) es una capa que traduce automáticamente entre objetos y filas. Escribes estacionRepositorio.guardar(estacion) y alguien genera el INSERT; lees estacion.getBicicletas() y alguien genera el SELECT.

Para valorar lo que aporta, mira lo que costaría hacerlo a mano con JDBC puro. Este sería el guardar de una estación sin ORM:

Veinte líneas para una tabla de cinco columnas. Multiplícalo por buscarPorId, buscarTodas, actualizar, eliminar, y luego por las seis tablas del modelo. Y todavía falta el ResultSet → objeto, el manejo de nulos, y que cada ALTER TABLE obliga a revisar todas esas posiciones de parámetro numeradas a mano.

Lo que un ORM aporta, ordenado por importancia real:

• Elimina el código repetitivo de mapeo. El 80 % de ese fragmento desaparece.
• Gestiona la identidad y el estado. Sabe qué objetos ha cargado y cuáles han cambiado, y genera el UPDATE solo de lo modificado.
• Traduce SQL específico de cada motor. El mismo código funciona sobre H2 en desarrollo y PostgreSQL en producción.
• Ofrece un lenguaje de consulta orientado a objetos (JPQL) que se valida contra el modelo, no contra cadenas.
• Automatiza la carga de asociaciones y ofrece control sobre cuándo cargarlas.

Y lo que un ORM no aporta, porque conviene decirlo desde el principio:

• No te exime de conocer SQL. Cuando algo va lento, el diagnóstico se hace leyendo el SQL generado.
• No convierte un modelo relacional malo en uno bueno.
• No es gratis: añade una capa con reglas propias que hay que entender (justo lo que hace este módulo).

Estas cuatro piezas se nombran a diario como si fueran intercambiables y no lo son. Cada una vive en un nivel de abstracción distinto y depende de la anterior.

La distinción crítica es JPA es una especificación, Hibernate es una implementación. JPA define que existe @Entity y qué debe significar; Hibernate escribe el código que hace que signifique eso. Otras implementaciones son EclipseLink y OpenJPA, pero Spring Boot trae Hibernate por defecto y es la elección estándar de facto.

Cada flecha hacia abajo es una traducción. estacionRepositorio.findById(1L) se convierte en una llamada a EntityManager.find(Estacion.class, 1L), que Hibernate traduce a un SELECT ... WHERE id = ?, que el driver JDBC envía por el socket a PostgreSQL. Cuando algo va mal, el diagnóstico consiste en bajar por estas capas hasta encontrar en cuál se rompió la traducción.

Un matiz que ahorra confusión: Spring Data JPA no sustituye a Hibernate, se apoya en él. Y Spring Data JPA no es Spring Data JDBC; comparten familia y el estilo de repositorios, pero por debajo son proyectos distintos (lo veremos en el apartado 8).

Como todo starter (02-06), es un POM sin código que arrastra un conjunto coherente de dependencias con versiones ya compatibles entre sí.

Esa única línea añade al classpath:

Lo que no incluye —deliberadamente— es el driver de la base de datos, porque el starter no puede saber a qué motor te vas a conectar. Añadir H2 o PostgreSQL es lo primero que haremos en 04-02.

Puedes comprobar el árbol real en tu proyecto:

Estos tres términos son el vocabulario básico de JPA. Confundirlos es la causa de la mitad de las preguntas de foro sobre «por qué no se guardan mis cambios».

Unidad de persistencia (persistence unit): la configuración completa de un almacén de datos —qué DataSource usar, qué clases son entidades, qué dialecto SQL, qué propiedades de Hibernate—. En una aplicación JPA clásica se declaraba en persistence.xml. En Spring Boot ese fichero no existe: la unidad de persistencia se construye a partir de application.yml y del escaneo automático de entidades. Es una de las cosas que el starter hace por ti.

EntityManager: la interfaz central de JPA. Es tu puerta de entrada a la persistencia. Sus operaciones esenciales:

Con Spring Data JPA casi nunca lo usarás directamente, porque los repositorios lo encapsulan. Pero está ahí debajo, y entender su comportamiento explica el de los repositorios.

Contexto de persistencia (persistence context): es el concepto que de verdad hay que interiorizar. Es una caché de primer nivel que el EntityManager mantiene con todas las entidades que ha cargado o guardado durante una unidad de trabajo. Tiene tres propiedades que lo cambian todo:

1. Garantiza identidad única: dentro del mismo contexto, dos búsquedas de la estación 1 devuelven exactamente el mismo objeto Java. estacionA == estacionB es true.
2. Detecta cambios automáticamente (dirty checking): guarda una copia del estado original; al hacer flush compara y genera un UPDATE solo si algo cambió. Por eso, sobre una entidad gestionada, no hace falta llamar a save() (lo desarrollaremos en 04-07).
3. Retrasa la escritura (write-behind): acumula el SQL y lo envía en el último momento, lo que permite agruparlo y ordenarlo.

En una aplicación Spring típica, el contexto de persistencia vive lo que dura la transacción, normalmente un método @Transactional del servicio. Fuera de él, las entidades quedan separadas. Ese vínculo entre contexto y transacción es el eje del módulo y el motivo de la lección 04-07.

Toda instancia de una clase @Entity está siempre en uno de estos cuatro estados. Saber en cuál está explica por qué un cambio se guarda o se pierde.

Recorramos los cuatro con una estación de Ribalta:

Dos consecuencias que sorprenden a todo el mundo la primera vez:

• El paso 2 no necesita save() explícito. Muchísimo código Spring lo llama «por si acaso»; es inofensivo pero revela que no se ha entendido el contexto de persistencia.
• El paso 3 sí lo necesita, y ahí save() no inserta: hace merge. La diferencia se detalla en 04-05.

El estado separado es el que produce la temida LazyInitializationException: intentar navegar una asociación perezosa de una entidad cuyo contexto ya se cerró. Lo veremos en 04-04.

En cuanto spring-boot-starter-data-jpa está en el classpath y hay un DataSource configurado, la autoconfiguración de 02-06 se dispara. Las clases implicadas son DataSourceAutoConfiguration, HibernateJpaAutoConfiguration y JpaRepositoriesAutoConfiguration, y entre todas registran estos beans sin que escribas una línea:

Además, escanea automáticamente las clases @Entity desde el paquete de la clase anotada con @SpringBootApplication hacia abajo. Como CicloUrbanaApplication vive en com.ciclourbana, todas las entidades de com.ciclourbana.estaciones, .bicicletas y .alquileres se detectan solas. Es la misma regla del escaneo de componentes de 01-04, aplicada a entidades.

Puedes verificarlo con el informe de autoconfiguración de 02-06:

En la sección Positive matches aparecerán entradas como:

Y si no configuras un DataSource teniendo el starter, el arranque falla con un mensaje muy característico:

Es exactamente el problema que resuelve la lección siguiente.

JPA es la opción por defecto, no la única ni siempre la mejor. Conocer el mapa evita el error de forzarla donde no encaja.

Un criterio práctico y honesto: JPA brilla cuando escribes y lees agregados de dominio; se estorba cuando haces informes. En CicloUrbana usaremos Spring Data JPA para todo el CRUD de estaciones, bicicletas y alquileres, y en 04-06 veremos consultas nativas para casos como «estaciones más cercanas», donde el SQL específico de PostgreSQL gana por goleada. No son excluyentes: conviven en el mismo proyecto sobre el mismo DataSource.

Este es el destino del módulo. Seis tablas que reflejan el negocio de la red de Ribalta:

Fíjate en tres detalles que anticipan lecciones concretas:

• La columna version en estaciones y bicicletas es el bloqueo optimista de 04-03, el que sustituirá al ShallowEtagHeaderFilter de 03-03.
• alquileres tiene dos claves ajenas a estaciones (origen y destino): un caso donde mappedBy no basta y hay que nombrar cada @JoinColumn explícitamente (04-04).
• importe y precio_minuto son numeric, nunca double. El porqué está en 04-03, y es una de las reglas menos negociables de todo el módulo.

El recorrido del módulo, apoyado en este modelo:

Creer que JPA es Hibernate. Son cosas distintas: JPA es la especificación, Hibernate la implementación. Importa cuando aparece una anotación como @BatchSize, que es de Hibernate, no de JPA: funciona, pero te ata al proveedor. Comprueba siempre el paquete del import: jakarta.persistence.* es estándar; org.hibernate.annotations.* es específico.

Pensar que un ORM te libra de saber SQL. Es exactamente al revés: cuanto más automática es la generación de SQL, más importante es saber leerlo. Activa el log de sentencias desde el primer día (04-02) y acostúmbrate a mirarlo.

Llamar a save() sobre una entidad ya gestionada. No hace daño, pero indica que no se ha entendido el dirty checking. Dentro de un método @Transactional, modificar una entidad cargada basta.

Olvidar que el contexto de persistencia muere con la transacción. Es el origen de la LazyInitializationException y de los «cambios que no se guardan». Cuando algo raro pase, la primera pregunta debe ser: ¿en qué estado está esta entidad?

Elegir JPA para todo, incluidos los informes. Una consulta de agregación sobre un millón de alquileres no debería pasar por el mapeo de entidades. JdbcTemplate o una consulta nativa con proyección es la respuesta correcta (04-06).

Consejo: dibuja el modelo relacional antes de anotar clases. El diagrama ER de arriba se hizo antes que las entidades, no después. Anotar sin un modelo pensado produce esquemas que hay que rehacer, y en 04-08 verás que rehacer un esquema en producción es caro.

Consejo: conserva la interfaz EstacionRepositorio. El módulo entero es la demostración de que aislar el almacenamiento tras una interfaz permite cambiar de tecnología sin tocar servicios ni controladores.

Dado el siguiente método de un servicio de CicloUrbana, indica en qué estado está la variable estacion en cada punto marcado y si el cambio de la línea final llega a la base de datos. Justifícalo.

Para cada necesidad del ayuntamiento de Ribalta, elige entre JdbcTemplate, Spring Data JPA, jOOQ o R2DBC, y razona la elección en una frase.

1. CRUD completo de estaciones con validación y relaciones con bicicletas.
2. Un informe mensual que cruza alquileres, usuarios y tarifas con seis JOIN, tres subconsultas y funciones de ventana.
3. Cargar de golpe 500 000 lecturas de sensores de las bicicletas cada noche.
4. Un panel en tiempo real que mantiene 20 000 conexiones abiertas mostrando la ocupación de las estaciones.

Explica, capa por capa, qué ocurre cuando EstacionService ejecuta estacionRepositorio.findById(3L) y la estación «Parque del Río» no está aún en el contexto de persistencia. Nombra las cinco capas implicadas y qué hace cada una.

Solución 1.

• (A) Transitorio. new Estacion() crea un objeto Java normal; Hibernate no lo conoce, no tiene id y nada lo vigila. Además, esta línea es inútil: la referencia se sobrescribe inmediatamente. Es un olor a código, no un error.
• (B) Gestionado. findById carga la fila y la incorpora al contexto de persistencia de la transacción abierta por @Transactional. Hibernate guarda una copia de su estado original para el dirty checking.
• (C) Gestionado y «sucio». El objeto sigue gestionado; su nombre difiere ahora de la copia original. Todavía no se ha ejecutado ningún UPDATE.
• (D) El cambio SÍ llega a la base de datos. Al terminar el método, el proxy transaccional hace commit; antes del commit se ejecuta un flush que compara estado actual y copia original, detecta el nombre modificado y emite UPDATE estaciones SET nombre = ? WHERE id = ?. Tras el commit el contexto se cierra y la entidad pasa a separada.

No hace falta llamar a save(). Es el ejemplo canónico de dirty checking. Si el método no llevara @Transactional, el contexto viviría solo lo que dura la llamada al repositorio, la entidad volvería separada y el cambio se perdería en silencio: el peor tipo de fallo, porque no lanza ninguna excepción.

Solución 2.

1. Spring Data JPA. Es su caso ideal: agregado de dominio, relaciones, validación, escritura y lectura por identificador. La productividad compensa de sobra la abstracción.
2. jOOQ (o JdbcTemplate con SQL nativo). Seis JOIN, subconsultas y funciones de ventana no son expresables cómodamente en JPQL, y forzarlo produce consultas ilegibles. jOOQ da SQL tipado y comprobado en compilación; JdbcTemplate es la alternativa sin dependencias añadidas.
3. JdbcTemplate con batchUpdate. Una carga masiva no debe pasar por el contexto de persistencia: 500 000 entidades gestionadas agotarían la memoria y el dirty checking haría un trabajo inútil. Inserción por lotes en JDBC directo.
4. R2DBC con WebFlux. Veinte mil conexiones concurrentes con el modelo bloqueante de JDBC exigirían veinte mil hilos. El acceso reactivo no bloqueante está pensado exactamente para esto. (Con Java 21 los hilos virtuales cambian parte de este cálculo, pero R2DBC sigue siendo la opción de manual.)

Solución 3.

1. EstacionService llama a estacionRepositorio.findById(3L) sobre la interfaz. No sabe nada de JPA.
2. El proxy de Spring Data JPA —creado en el arranque, como veremos en 04-05— recibe la llamada y la delega en SimpleJpaRepository, la implementación estándar.
3. SimpleJpaRepository traduce a entityManager.find(Estacion.class, 3L) y envuelve el resultado en Optional.
4. El EntityManager (Hibernate) busca primero en el contexto de persistencia. Como no está, genera el SQL adaptado al dialecto: select e1_0.id, e1_0.capacidad, ... from estaciones e1_0 where e1_0.id=?.
5. JDBC y el driver de PostgreSQL piden una conexión al pool HikariCP, envían la sentencia preparada y devuelven un ResultSet.

De vuelta, Hibernate construye la instancia de Estacion, la registra en el contexto de persistencia con una copia de su estado, y la devuelve envuelta en Optional. Si el servicio volviera a pedir la estación 3 en la misma transacción, el paso 5 no se repetiría: la caché de primer nivel devolvería el mismo objeto.

Ya tienes el mapa completo del terreno. Sabes que el desfase objeto-relacional no es un capricho sino cinco desencuentros concretos entre dos modelos igual de válidos, y que un ORM existe para absorberlos a cambio de introducir reglas propias. Distingues con precisión las cuatro piezas que se confunden a diario: JDBC como API de bajo nivel, JPA como especificación, Hibernate como implementación que genera el SQL real, y Spring Data JPA como capa que fabrica repositorios a partir de interfaces. Conoces las siete dependencias que arrastra spring-boot-starter-data-jpa y, sobre todo, la que no arrastra: el driver. Entiendes qué es el contexto de persistencia y sus tres propiedades —identidad única, dirty checking y escritura diferida—, que explican por qué modificar una entidad gestionada basta para guardarla. Puedes situar cualquier instancia en uno de los cuatro estados y predecir si sus cambios sobrevivirán. Sabes qué beans crea la autoconfiguración en cuanto detecta el starter y cómo verificarlo con --debug. Y tienes criterio para saber cuándo JPA no es la respuesta y conviene JdbcTemplate, jOOQ o R2DBC.

También tienes el destino a la vista: las seis tablas del modelo de CicloUrbana, con su columna version para el bloqueo optimista, sus dos claves ajenas de alquileres a estaciones y sus importes en numeric.

Falta lo primero de todo: no hay ninguna base de datos. Si añades el starter ahora mismo y arrancas, la aplicación fallará con «Failed to configure a DataSource». La lección 04-02, Configuración de Fuentes de Datos, resuelve eso: montaremos H2 en memoria para desarrollo con su consola web, levantaremos PostgreSQL 16 con un docker-compose.yml propio de CicloUrbana, afinaremos el pool HikariCP parámetro a parámetro con criterios de dimensionado reales, decidiremos qué valor de ddl-auto usar en cada entorno y por qué open-in-view debe desactivarse desde el primer día, y dejaremos el log de SQL configurado para poder ver exactamente qué envía Hibernate a Ribalta.