Hibernate hbm2ddl.auto: valores, ejemplos y funcionamiento interno

Introducción: por qué hbm2ddl.auto es tanto una salvación como un dolor de cabeza

Cualquiera que haya configurado Hibernate (o Spring Boot + JPA) al menos una vez se ha encontrado con la misteriosa línea en application.properties o hibernate.cfg.xml:

spring.jpa.hibernate.ddl-auto=update\n# o\nhibernate.hbm2ddl.auto=create\n

En Stack Overflow, esta pregunta ha acumulado cientos de miles de visitas. Y con razón: un valor incorrecto puede destruir tus datos, mientras que uno correcto puede ahorrarte horas de trabajo. En este artículo, analizaremos todos los valores posibles de hibernate.hbm2ddl.auto, mostraremos ejemplos reales de código en Java y exploraremos su funcionamiento interno para entender cómo Hibernate gestiona realmente el esquema de la base de datos.

¿Qué es hbm2ddl.auto y para qué sirve?

Hibernate hbm2ddl.auto es un parámetro de configuración que controla la creación, actualización o validación automática del esquema de la base de datos basándose en tus entidades (Entity). En otras palabras, Hibernate observa las clases con anotaciones @Entity, @Table, @Column y genera sobre la marcha consultas SQL como CREATE TABLE, ALTER TABLE, etc.

Esto es increíblemente útil durante el desarrollo, pero puede convertirse en un desastre en producción si no entiendes cómo funciona cada valor internamente.

Lista completa de valores posibles de hibernate.hbm2ddl.auto

Hibernate admite exactamente cinco valores (además de none como ausencia de acción):

\n
• validate — solo validación del esquema
\n
• update — actualización automática
\n
• create — creación desde cero al iniciar
\n
• create-drop — creación al iniciar y eliminación al detener
\n
• none — no hacer nada (valor por defecto)
\n

Analicemos cada valor en detalle, con ejemplos y explicación de lo que ocurre «bajo el capó».

1. validate — validación, pero sin cambios

Cómo funciona: Al iniciar la aplicación, Hibernate compara tus entidades Java con la estructura real de las tablas en la base de datos. Si todo coincide, la aplicación se inicia. Si no, Hibernate lanza una excepción SchemaValidationException.

Ejemplo de configuración:

// application.properties\nspring.jpa.hibernate.ddl-auto=validate\n

Ejemplo de entidad:

@Entity\n@Table(name = "users")\npublic class User {\n    @Id\n    @GeneratedValue(strategy = GenerationType.IDENTITY)\n    private Long id;\n    \n    @Column(name = "email", nullable = false, length = 255)\n    private String email;\n    \n    @Column(name = "age")\n    private Integer age;\n}\n

Qué ocurre bajo el capó: Hibernate lee los metadatos de la entidad, forma una representación interna de la tabla users con las columnas id, email (NOT NULL, longitud 255), age. Luego ejecuta una consulta SQL a information_schema (o su equivalente en tu BD) y compara tipos, nullable y longitudes. Si en la BD la columna email es de tipo VARCHAR(100), se producirá un error.

Cuándo usarlo: Ideal para producción, para asegurarse de que las migraciones (Liquibase/Flyway) no hayan roto la correspondencia con el código.

2. update — actualización automática (¡con precaución!)

Cómo funciona: Hibernate agrega automáticamente nuevas tablas, columnas y restricciones si no existen en la BD. Pero nunca elimina columnas ni tablas, incluso si las has quitado del código Java.

Ejemplo de configuración:

// application.properties\nspring.jpa.hibernate.ddl-auto=update\n

Ejemplo de cambio