Skip to content
Anjunar/ DOCS

Hibernate DDL Manager

Controlled schema evolution from Hibernate metadata. The server migrates the database at startup, and renames stay renames because every table and column carries a stable ID.

1.0.1Current release
JVMRuns on
Scala 3.9Language version
MITLicense

Installation

schema-integration brings every other module along. The application provides Hibernate ORM 7.4 and the PostgreSQL JDBC driver.

sbt
libraryDependencies += "com.anjunar.hibernateddl" %% "schema-integration" % "1.0.1"
xml
<dependency> <groupId>com.anjunar.hibernateddl</groupId> <artifactId>schema-integration_3</artifactId> <version>1.0.1</version> </dependency>

A rename, not a drop

The entity and its properties carry IDs. Rename the field and its column, keep the ID, and the next start renames the column in place.

scala
import com.anjunar.hibernateddl.hibernate.annotation.SchemaId import jakarta.persistence.* import scala.compiletime.uninitialized @Entity @SchemaId("7f3a9c21") @Table(name = "customer") class Customer: @Id @SchemaId("0a1b2c3d") var id: java.lang.Long = uninitialized @SchemaId("f34e45b6") @Column(name = "alias") var alias: String = uninitialized // was nick_name
Output
ALTER TABLE "public"."customer" RENAME COLUMN "nick_name" TO "alias";

Switch it on

Three Hibernate settings turn the migration on. Hibernate itself may only validate afterwards.

properties
hibernate.ddl_manager.enabled=true hibernate.hbm2ddl.auto=validate hibernate.default_schema=public
01 / Identity

Stable IDs instead of names

Eight random hex digits per entity and property, assigned once. Names may change freely; the ID tells the framework what stayed.

02 / History

A stored model instead of scripts

Every migration stores its target model in the database. The next start plans against it, so a server may skip releases.

03 / Safety

Refuse instead of guess

What loses data needs an approval, what cannot be planned is refused with a message. Nothing is guessed.

Contents

From the first ID to the running server

Start with stable IDs and the startup migration; the other pages cover changes that need a decision.

BasicsStable IDsHow @SchemaId turns a rename into a rename instead of a drop and a create.Migrating at startupThe integrator, the explicit call and what happens inside one migration.
ChangesApprovalsDrops, renames back and reverts run only when each one is approved.Required columns and backfillsHow a column becomes required, and how existing rows get their values.
OperationsPreviewWhat the next start would do to a database, read-only, from code or the command line.Existing databasesAdopting a database without history and accepting changes migrated by hand.
ReferenceSettingsEvery hibernate.ddl_manager setting and every execution option.Scope and limitsWhat can be mapped, which changes are planned and what is refused.