Migration beim Start · Hibernate DDL Manager

Integrator

Der Normalfall: eine Hibernate-Einstellung

Mit schema-integration im Klassenpfad schalten Hibernate-Einstellungen die Migration ein. Während Hibernate die SessionFactory baut, noch vor der eigenen Validierung, liest der Integrator die Entities und migriert über eine Verbindung von Hibernate.

hibernate.ddl_manager.enabled=true hibernate.hbm2ddl.auto=validate hibernate.default_schema=public

Voraussetzungen

PostgreSQL 14 oder neuer und Hibernate ORM 7.4.

Jede Tabelle und Sequenz hat ein Schema, aus @Table(schema) oder hibernate.default_schema.

hbm2ddl.auto und schema-generation.database.action sind leer, none oder validate.

Eine unbekannte Einstellung unter hibernate.ddl_manager ist ein Fehler, damit kein Tippfehler eine Sicherung abschaltet.

Expliziter Aufruf

Wenn der Server den Bootstrap selbst steuert

Mit JTA oder Multi-Tenancy verweigert der Integrator. Rufe die Migration dann selbst auf, zwischen Metadaten und SessionFactory, mit einer DataSource, deren Verbindungen nicht in JTA eingebunden sind.

import com.anjunar.hibernateddl.executor.ExecutionOptions import com.anjunar.hibernateddl.integration.HibernateSchemaMigration val metadata = MetadataSources(registry).addAnnotatedClass(classOf[Customer]).buildMetadata() val result = HibernateSchemaMigration.migrate(metadata, dataSource, ExecutionOptions(lockTimeoutMillis = 5000)) println(s"${result.status}: revision ${result.revision}, ${result.statementCount} statements") val sessionFactory = metadata.buildSessionFactory()

Applied: revision 4, 3 statements

migrate läuft synchron. Mit jedem MigrationStatus darf der Server weiterlaufen; eine MigrationException muss den Start abbrechen. Einstellungen in der Registry verfeinern die übergebenen Optionen.

Historie

Keine Migrationsskripte, keine Snapshots

Jede Migration speichert ihr Zielmodell als JSON in __hibernate_ddl.schema_history. Der nächste Start plant gegen dieses Modell. Weil IDs über alle Versionen stabil sind, darf ein Server Versionen überspringen. Ohne Historie ist das vorige Modell leer, und alle Tabellen werden angelegt.

Applied: Änderungen wurden geplant und ausgeführt; eine neue Revision ist geschrieben.
AlreadyApplied: Die Datenbank entspricht bereits dem Ziel; nur geprüft.
Adopted: Eine Datenbank ohne Historie entsprach dem Ziel und wurde Revision 1.
ManuallyMigrated: Ein von Hand migriertes Ziel wurde geprüft und eingetragen.

Eine Transaktion

Was unter der Sperre passiert

Unter einer transaktionalen Advisory-Sperre prüft der Executor die Historie, plant die Änderungen, vergleicht die Datenbank mit dem gespeicherten Modell, führt das DDL aus, prüft das Ziel und schreibt die neue Revision, alles in einer Transaktion.

Drift

Handänderungen stoppen den Start

Eine Datenbank, die vom gespeicherten Modell abweicht, wird nicht weiter migriert.

Reihenfolge

Ein älterer Server startet nicht

Nach einer neueren Migration würde ein älteres Modell zurückbenennen oder löschen. Das wird abgelehnt.

Sperren

Andere Knoten arbeiten weiter

Ein Start ohne Änderungen prüft nur unter einer geteilten Sperre; laufende Knoten lesen und schreiben weiter.

Tabellen sind gesperrt, solange DDL läuft

Eine Migration mit Änderungen sperrt ihre Tabellen exklusiv bis zum Commit. Plane große Änderungen für ein Wartungsfenster.