Home

Liquibase Hibernate Extension

This Liquibase extension lets you use your Hibernate configuration as a comparison database for diff, diffChangeLog and generateChangeLog.

Normal workflow using this extension is:

1. Edit your Hibernate mapped classes as needed (add and remove classes and attributes)
2. Run liquibase --changeLogFile=changelog.xml --url=jdbc:yourdatabase --referenceUrl=hibernate:classic:path/to/hibernate.cfg.xml diffChangeLog
3. Check that the modified changelog.xml does what you expect, edit it if it does not
4. Run liquibase --changeLogFile=changelog.xml --url=jdbc:yourdatabase update
5. Repeat

If you specify an existing changeLogFile, each run of diffChangeLog will append to the file.

Why not use HBM2DDL?

1. The Hibernate documentation says not to use it for production
2. Stack Overflow says not to use it

The main problem with HBM2DDL is that it automatically applies changes that it thinks is right. For many cases that can be fine, but as with any diff-based database tool it can easily destroy data because it matters HOW the database gets from state A to state B. For example, if you rename your Person class to Employee, hbm2ddl will just create a new table called EMPLOYEE rather than perform the rename you want.

What makes Liquibase different is that it does not figure out changes based on schema comparisons but instead runs the changes you said need to be made. The Liquibase Hibernate extension makes creating those changes easier by automatically creating a rough draft of those changes. Most of the time the changes can be run directly, but in the cases where it guesses wrong you have the opportunity to fix the proposed changes before they are applied to your database and all other databases down the pipeline.

Usage

Once installed (see below), the liquibase-hibernate integration allows you to treat your hibernate configuration and classes like any other database by using a special connection url syntax.

Three styles of connection URLs are supported:

hibernate:classic

The hibernate classic URL allows you to either reference your hibernate config XML file or specify a class name that implements liquibase/ext/hibernate/customfactory/CustomClassicConfigurationFactory

Database URL Examples:

hibernate:classic:com/example/hibernate.cfg.xml
hibernate:classic:hibernate.cfg.xml
hibernate:classic:com.example.MyConfigFactory
hibernate:classic:com/example/hibernate.cfg.xml?hibernate.ejb.naming_strategy=org.hibernate.cfg.ImprovedNamingStrategy

hibernate:ejb3

The hibernate ejb3 URL allows you to either reference a persistence-unit defined in your persistence.xml or specify a class name that implements liquibase/ext/hibernate/customfactory/CustomEjb3ConfigurationFactory

Database URL Examples:

hibernate:ejb3:myPersistenceUnit
hibernate:ejb3:com.example.MyConfigFactory
hibernate:ejb3:myPersistenceUnit?hibernate.ejb.naming_strategy=org.hibernate.cfg.ImprovedNamingStrategy

hibernate:spring

The hibernate spring URL allows you to either reference your bean within a spring config or specify a comma separated list of packages containing hibernate or javax.persistence annotated classes to use. Spring is a required dependency, even if you are listing a package and not a spring class.

• If you are defining a spring config file, bean is a required URL parameter.
• If you are defining a package to scan, dialect is a required URL parameter.

Database URL Examples:

hibernate:spring:com/example/spring.xml?bean=sessionFactory
hibernate:spring:com.example?dialect=org.hibernate.dialect.MySQL5Dialect
hibernate:spring:com.example.employee,com.example.auction?dialect=org.hibernate.dialect.MySQL5Dialect

Spring Boot

Spring Boot uses its own Hibernate naming strategies, so to get Liquibase to use these they need to be specified in the database URL. The following is for Hibernate 5:

hibernate:spring:com.example?dialect=org.hibernate.dialect.MySQL5Dialect&hibernate.physical_naming_strategy=org.springframework.boot.orm.jpa.hibernate.SpringPhysicalNamingStrategy&hibernate.implicit_naming_strategy=org.springframework.boot.orm.jpa.hibernate.SpringImplicitNamingStrategy

URL Parameters

For all url styles, you can specify hibernate parameters using URL-style format such:

hibernate:classic:com/example/hibernate.cfg.xml?hibernate.ejb.naming_strategy=org.hibernate.cfg.ImprovedNamingStrategy

Any properties defined in the URL will override parameters set in the standard configuration file(s). The following parameters are supported:

• dialect: the dialect use for generating the proper SQL
• hibernate.ejb.naming_strategy: the naming convention of database objects and schema elements
• hibernate.enhanced_id: set to true to enable hibernate.id.new_generator_mappings, table id generator (@TableGenerator) will use this parameter to determine the appropriate schema
• hibernate.physical_naming_strategy: Hibernate5 physical naming strategy
• hibernate.implicit_naming_strategy: Hibernate5 implicit naming strategy

Installation

Simply download the liquibase-hibernate jar from the release page and add it to your classpath. You can also add a dependency through Maven (group: org.liquibase.ext, artifact liquibase-hibernate3, liquibase-hibernate4 or liquibase-hibernate5)

If you are using the command line version of Liquibase, you simply have to add the liquibase-hibernate[3|4|5].jar file to the LIQUIBASE_HOME/lib directory.

Compatiblity

Use liquibase-hibernate5.jar or liquibase-hibernate6.jar depending on your hibernate version.

This extension can be used with any method of running Liquibase (command line, Gradle, Maven, Ant, etc.)

Project Interaction

Use the issue tracker to log any issues or feature requests

Pull requests are greatly appreciated