Hibernate hbm2ddl.auto : valeurs, exemples et fonctionnement interne

Introduction : pourquoi hbm2ddl.auto est à la fois un salut et un casse-tête

Quiconque a déjà configuré Hibernate (ou Spring Boot + JPA) a rencontré la mystérieuse ligne dans application.properties ou hibernate.cfg.xml :

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

Sur Stack Overflow, cette question a recueilli des centaines de milliers de vues. Et pour cause : une mauvaise valeur peut détruire vos données, tandis qu'une bonne peut vous faire gagner des heures de travail. Dans cet article, nous allons détailler toutes les valeurs possibles de hibernate.hbm2ddl.auto, montrer des exemples de code réels en Java et regarder sous le capot pour comprendre comment Hibernate gère réellement le schéma de la base de données.

Qu'est-ce que hbm2ddl.auto et à quoi sert-il ?

Hibernate hbm2ddl.auto est un paramètre de configuration qui contrôle la création, la mise à jour ou la validation automatique du schéma de la base de données en fonction de vos entités (Entity). En d'autres termes, Hibernate examine les classes avec les annotations @Entity, @Table, @Column et génère à la volée les requêtes SQL CREATE TABLE, ALTER TABLE, etc.

C'est incroyablement pratique en phase de développement, mais cela peut devenir une catastrophe en production si vous ne comprenez pas comment chaque valeur fonctionne en interne.

Liste complète des valeurs possibles de hibernate.hbm2ddl.auto

Hibernate prend en charge exactement cinq valeurs (plus none comme absence d'action) :

\n
• validate — uniquement la validation du schéma
\n
• update — mise à jour automatique
\n
• create — création à nouveau au démarrage
\n
• create-drop — création au démarrage et suppression à l'arrêt
\n
• none — ne rien faire (valeur par défaut)
\n

Examinons chaque valeur en détail, avec des exemples et une explication de ce qui se passe « sous le capot ».

1. validate — validation, mais pas de modification

Comment ça fonctionne : Au démarrage de l'application, Hibernate compare vos entités Java avec la structure réelle des tables dans la base de données. Si tout correspond, l'application démarre. Sinon, Hibernate lève une exception SchemaValidationException.

Exemple de configuration :

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

Exemple d'entité :

@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

Ce qui se passe sous le capot : Hibernate lit les métadonnées de l'entité, forme une représentation interne de la table users avec les colonnes id, email (NOT NULL, longueur 255), age. Ensuite, il exécute une requête SQL vers information_schema (ou l'équivalent dans votre base de données) et compare les types, nullable, longueurs. Si dans la base de données la colonne email est de type VARCHAR(100), une erreur sera levée.

Quand l'utiliser : Idéal pour la production, afin de s'assurer que les migrations (Liquibase/Flyway) n'ont pas violé la correspondance avec le code.

2. update — mise à jour automatique (avec prudence !)

Comment ça fonctionne : Hibernate ajoute lui-même les nouvelles tables, colonnes et contraintes si elles ne sont pas présentes dans la base de données. Mais il ne supprime jamais les colonnes et les tables, même si vous les avez retirées du code Java.

Exemple de configuration :

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

Exemple de mod