Hibernate hbm2ddl.auto: valores, exemplos e funcionamento interno

Introdução: por que hbm2ddl.auto é tanto uma salvação quanto uma dor de cabeça

Todo mundo que já configurou Hibernate (ou Spring Boot + JPA) já se deparou com a misteriosa linha em application.properties ou hibernate.cfg.xml:

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

No Stack Overflow, essa pergunta acumulou centenas de milhares de visualizações. E não é à toa: um valor incorreto pode destruir seus dados, enquanto o valor certo pode economizar horas de trabalho. Neste artigo, vamos analisar todos os valores possíveis de hibernate.hbm2ddl.auto, mostrar exemplos reais de código em Java e mergulhar nos bastidores para entender como o Hibernate realmente gerencia o esquema do banco de dados.

O que é hbm2ddl.auto e para que serve?

Hibernate hbm2ddl.auto é um parâmetro de configuração que controla a criação, atualização ou validação automática do esquema do banco de dados com base em suas entidades (Entity). Em outras palavras, o Hibernate analisa as classes com anotações @Entity, @Table, @Column e gera dinamicamente comandos SQL como CREATE TABLE, ALTER TABLE, etc.

Isso é extremamente conveniente durante o desenvolvimento, mas pode se tornar um desastre em produção se você não entender como cada valor funciona internamente.

Lista completa de valores possíveis para hibernate.hbm2ddl.auto

O Hibernate suporta exatamente cinco valores (mais none como ausência de ação):

\n
• validate — apenas validação do esquema
\n
• update — atualização automática
\n
• create — criação do zero na inicialização
\n
• create-drop — criação na inicialização e exclusão na parada
\n
• none — não fazer nada (valor padrão)
\n

Vamos detalhar cada valor, com exemplos e explicação do que acontece "por baixo dos panos".

1. validate — validação, mas sem alteração

Como funciona: Ao iniciar a aplicação, o Hibernate compara suas entidades Java com a estrutura real das tabelas no banco de dados. Se tudo coincidir, a aplicação inicia. Caso contrário, o Hibernate lança uma exceção SchemaValidationException.

Exemplo de configuração:

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

Exemplo de entidade:

@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

O que acontece nos bastidores: O Hibernate lê os metadados da entidade, cria uma representação interna da tabela users com as colunas id, email (NOT NULL, tamanho 255), age. Em seguida, executa uma consulta SQL no information_schema (ou equivalente no seu banco) e compara tipos, nullable e tamanhos. Se no banco a coluna email for do tipo VARCHAR(100) — ocorrerá um erro.

Quando usar: Ideal para produção, para garantir que as migrações (Liquibase/Flyway) não quebraram a correspondência com o código.

2. update — atualização automática (com cuidado!)

Como funciona: O Hibernate adiciona automaticamente novas tabelas, colunas e restrições se elas não existirem no banco. No entanto, ele nunca remove colunas ou tabelas, mesmo que você as tenha removido do código Java.

Exemplo de configuração:

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

Exemplo de alt