Liquibase Hibernate Integration
This is a Liquibase extension for connecting to Hibernate. The extension lets you use your Hibernate configuration as a comparison database for diff, diffChangeLog, and generateChangeLog in Liquibase.
Configuring the extension
These instructions will help you get the extension up and running on your local machine for development and testing purposes. This extension has a prerequisite of Liquibase core in order to use it. Liquibase core can be found at https://www.liquibase.org/download.
Compatiblity
The Liquibase Hibernate extension requires Liquibase 4.x and Java 1.8+. Use liquibase-hibernate5.jar
or liquibase-hibernate6.jar
depending on your Hibernate version.
Ideally the extension version should be the same one as Liquibase version.
This extension can be used with any method of running Liquibase (Command line, Gradle, Maven, Ant, and others.)
Liquibase CLI
Download the latest released Liquibase extension .jar
file and place it in the liquibase/lib
install directory. If you want to use another location, specify the extension .jar
file in the classpath
of your liquibase.properties file.
Maven
This extension is available in the maven repository under group org.liquibase.ext, artifacts:
- liquibase-hibernate6 Hibernate 6.0+ support
- liquibase-hibernate5 Hibernate 5.0+ support
Specify the Liquibase extension in the <dependency>
section of your POM file by adding the org.liquibase.ext
dependency for the Liquibase plugin.
<plugin>
<!--start with basic information to get Liquibase plugin:
include <groupId>, <artifactID>, and <version> elements-->
<groupId>org.liquibase</groupId>
<artifactId>liquibase-maven-plugin</artifactId>
<version>4.19.0</version>
<configuration>
<!--set values for Liquibase properties and settings
for example, the location of a properties file to use-->
<propertyFile>liquibase.properties</propertyFile>
</configuration>
<dependencies>
<!--set up any dependencies for Liquibase to function in your
environment for example, a database-specific plugin-->
<dependency>
<groupId>org.liquibase.ext</groupId>
<artifactId>liquibase-hibernate</artifactId>
<version>${liquibase-hibernate.version}</version>
</dependency>
</dependencies>
</plugin>
Contribution
To file a bug, improve documentation, or contribute code, follow our guidelines for contributing.
This step-by-step instructions will help you contribute code for the extension.
Once you have created a PR for this extension you can find the artifact for your build using the following link: https://github.com/liquibase/liquibase-hibernate/actions/workflows/build.yml.
Hibernate 5 vs. Hibernate 6
The master branch is Hibernate 6+ compatible.
The hibernate5
branch is Hibernate 5.6+ compatible.
Ideally changes should go into the hibernate5
branch and then be merged into master in order to support Hibernate 5 and 6.
Documentation
Using Liquibase with Hibernate
More Information
For more information, see the project wiki.
Issue Tracking
Any issues can be logged in the Github issue tracker.
License
This project is licensed under the Apache License Version 2.0.
Using Liquibase Test Harness' Diff test
Liquibase's Hibernate extension uses Liquibase Test Harness for integration testing.
The HibernateDiffCommandTest
class extends the DiffCommandTest
class from Test Harness and utilizes the ability to check differences between two databases.
As Hibernate is not a Relational database, this is our method of checking that database objects generated/updated by the Liquibase Hibernate extension against a database have the correct attributes.
In general the DiffCommandTest
works by utilizing the Liquibase diff command to check
differences between two databases, then it creates a changelog file based on diff, then it applies these changes to the target database and checks the diff again.
There still could be some differences afterwards as different DBs support different features, so while checking diffs again the test will ignore diffs that are expected.
Configurations for this test are hosted in 2 files:
src/test/resources/harness-config.yml
-- this is a general config file for Test Harness where DB connection details are specified.src/test/resources/liquibase/harness/diff/diffDatabases.yml
-- this file specifies which DBs should be compared and what the diffs are expected even after we try to bring the target DB to same state as the reference DB.
The DiffCommandTest
will take all pairs of targetDB-referenceDB from diffDatabases.yml
. The test also takes the *.cfg.xml
configuration files into consideration. And then the paths to these config files work as the DB connection URLs in the harness-config.yml
file.