Using Liquibase with Hibernate

Hibernate is an object-relational mapping (ORM) tool that can be used alongside Liquibase to provide a persistent framework for a relational database.

The purpose of this document is to guide you through the process of creating a new Liquibase project and integrating it into your Hibernate ORM setup. In this tutorial, you will learn how to install the required database drivers and configure the liquibase.properties file to establish a connection to an H2 database.

Supported versions

  • 5.0+: liquibase-hibernate5
  • 4.3: liquibase-hibernate4
  • 4.0–4.2: liquibase-hibernate4.2
  • 3.X: liquibase-hibernate3

Verification level

Unverified: Liquibase has not assessed how well this database works. Not supported by the Liquibase customer support team.

Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Open Source and Liquibase Pro. For more information, see Liquibase Database Tutorials.

Prerequisites

  • Download and install Maven.

Note: We will refer to the location of the Liquibase executable as $LIQUIBASE_HOME in this tutorial.

Install drivers

Hibernate can be used with several databases that are supported by Liquibase, such as H2.

Test your connection

To start the H2 server included in the Liquibase distribution, open the command line, go to $LIQUIBASE_HOME/examples, and run liquibase init start-h2. This opens a database console in your browser.

You can check the status of the database by entering create table test_table (id int) in the text area of the database console and selecting Run. You will see TEST_TABLE appear in the object view. For more information, see Using Liquibase with H2 .

Create a new Liquibase project with Hibernate

We will be creating a Maven project for this tutorial. To configure a Liquibase project for Hibernate, perform the following steps:

  1. Specify the database URL in the Liquibase properties file. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard JDBC format:
  2. url=hibernate:ejb3:com.liquibase.hibernate.tutorial.jpa

    Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: liquibaseProLicenseKey: <paste code here>

  3. Create a pom.xml file in your project directory and add the following content to the file:
  4. Get the additional dependencies by running the following command from the same directory as the pom.xml file:
  5. mvn dependency:copy-dependencies -DoutputDirectory=${project.build.directory}/lib -Dhttps.protocols=TLSv1.2

    Copy the following jars from ./target/lib to $LIQUIBASE_HOME/lib:

    • byte-buddy-1.10.10.jar
    • classmate-1.5.1.jar
    • dom4j-2.1.3.jar
    • hibernate-commons-annotations-5.1.0.Final.jar
    • hibernate-core-5.4.21.Final.jar
    • jandex-2.1.3.Final.jar
    • javax.persistence-api-2.2.jar
    • jboss-logging-3.3.2.Final.jar
    • jboss-transaction-api_1.2_spec-1.1.1.Final.jar
  6. Create a JPA configuration file at META-INF/persistence.xml. The persistence.xml file should contain the following content:
  7. Create the folder src/main/java/com/liquibase, which will be used for entity classes. In this directory, create a file House.java in a text editor and add the following content:
  8. Create a second file Item.java in the same directory and paste the following:
  9. If you haven't already, first install the application using the mvnw install command, or mvnw.cmd install for Windows. The generated JAR is what is referenced in the liquibase.properties file:
  10. classpath=target\\hibernate-liquibase-0.0.1-SNAPSHOT.jar
  11. Next, generate a dbchangelog.xml file from Hibernate in your project folder:
  12. liquibase --log-level=INFO --defaultsFile=src/main/resources/liquibase.properties generate-changelog
  13. Verify the project configuration by running the Liquibase status command. Open a command prompt and go to the project folder. Run the following command:
  14. liquibase --log-level=INFO --defaultsFile=src/main/resources/liquibase.properties status

    Example output

    Liquibase command 'status' was executed successfully.
  15. From a database UI tool, ensure that your database contains the table you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Congratulations!

You have successfully configured your project and can begin creating changesets to migrate changes to your database using Hibernate.

Source code is available at: https://github.com/juliuskrah/hibernate-liquibase

Supported commands and Change Types

For information on supported Liquibase Commands and Liquibase Change Types, go to Liquibase Database Tutorials and select the type of database you are using Hibernate with.

Related links