Schema Generation and Tooling

This section documents Hibernate ORM 7.4.x (User Guide, Introduction, Query Language Guide, Data Repositories Guide), Jakarta Persistence 3.2, Hibernate Search 8.4.x, and the Hibernate Validator / Hibernate Reactive references — which are the references these pages are written and verified against.

This content was generated with the assistance of AI and should be verified against those official docs before being relied on in production.

Three older reference books were consulted as bibliography only while preparing these pages and are not the primary or main source for any page. All three predate Jakarta Persistence 3.2 and Hibernate ORM 6/7 (the javax.persistence → jakarta.persistence namespace change, the ORM 6 query-engine rewrite, the Hibernate Search 6+ Elasticsearch backend), so the official documentation above wins on any discrepancy.

This section’s bibliography lists the reference material consulted while preparing these pages.

Hibernate (JPA & ORM) already states the core rule: schema generation is a development convenience, migrations own production schema. This page covers the generation settings and mapping annotations in full, plus the build tooling around Hibernate.

hibernate.hbm2ddl.auto and the jakarta.persistence.schema-generation.* settings

Value Behavior

none

Hibernate never touches the schema.

validate

Compares the mappings against the existing schema at startup and fails fast if they disagree — catches drift between code and a migration-tool-owned schema before the first query does.

update

Attempts to alter the existing schema to match the mappings. Never drops or renames anything (so a renamed column becomes an orphaned old column plus a new one), and its inference is not always correct for complex changes — development convenience only.

create / create-drop

Drops (if present) and recreates the schema at startup / also drops it again at shutdown. For a fresh local database or a test run only.

The portable JPA equivalent is the jakarta.persistence.schema-generation.* property family (jakarta.persistence.schema-generation.database.action, .scripts.action to instead emit DDL to a file rather than run it) — functionally overlapping with hibernate.hbm2ddl.auto but standardized across providers; most Hibernate-specific documentation and this section’s examples use the native property.

import.sql and ordered init scripts

A file named import.sql on the classpath (or a location set via jakarta.persistence.sql-load-script-source) is executed automatically after schema generation — handy for seeding lookup/reference data in a dev/test database created with create/create-drop. For anything beyond a handful of seed rows, or anything that must run in production, prefer the migration tool’s own seed-data mechanism instead (see Evolving the Database Model) — import.sql has no concept of "already ran" and simply re-executes every time the schema is (re)created.

@Check, @ColumnDefault, @Index, @UniqueConstraint

Mapping-level annotations that schema-generation tooling honors when producing DDL:

@Entity
@Table(
    name = "book",
    uniqueConstraints = @UniqueConstraint(columnNames = "isbn"),
    indexes = @Index(name = "idx_book_published_year", columnList = "published_year"))
public class Book {
    @Check(constraints = "price >= 0")
    private BigDecimal price;

    @ColumnDefault("true")
    private boolean active;
}

All four are DDL-generation hints only — they influence what create/update emit, but Hibernate never enforces @Check/@UniqueConstraint itself at runtime (a CHECK/UNIQUE violation surfaces only as a database-level SQLException translated by the JDBC driver, not caught earlier by Hibernate). On a migration-owned schema (hibernate.hbm2ddl.auto=validate), these annotations play no generation role at all — the actual constraints live in the migration scripts, and only Hibernate’s own runtime queries/writes are affected.

Gradle/Maven plugins

  • Bytecode enhancement plugin — rewrites compiled entity classes to support lazy loading of basic attributes and collections without a proxy subclass (see Fetching & N+1), and dirty-checking without a snapshot comparison. Configured as a build-time bytecode transformation step, not a runtime dependency.

  • Static metamodel generation — the hibernate-jpamodelgen annotation processor generates the Book_-style metamodel classes Criteria API uses, as a normal annotationProcessorPath/provided-scope dependency, no separate plugin needed on most build setups.

  • Schema management — the same hbm2ddl machinery is also exposed as standalone Gradle/Maven tasks/goals for generating a DDL script file offline (CI, review) without booting the whole application.

Hibernate Tools reverse engineering

Hibernate Tools can generate entity classes and mappings from an existing database schema (reverse engineering) — the inverse direction from everything else on this page, useful when onboarding Hibernate onto a database that already exists and was not designed alongside the entity model. It ships as an Ant task, a Gradle plugin, and an Eclipse plugin (no first-class Maven plugin); output is a starting point to review and refine by hand, not a finished mapping — reverse-engineered associations, inheritance, and identifier strategies rarely match what a hand-designed mapping would choose.

Links