Migrating with Liquibase Change Types

This page describes how to update your database using a Change Types specified in an XML, YAML, or JSON changelog.

Prerequisites

Before performing any of these steps, you must be able to connect to a local or remote database, accessible via command line or IDE/GUI.

For this example, we are going to use an H2 database. Review Using Liquibase with H2 Database Engine to get started.

View the Supported Databases topic for more information on which databases we support or for more information on running each database with Liquibase.

Step 1: Create or generate a changelog file

To complete your first migration, you must have a Changelog. The changelog file is where all your database changes are defined. Using Liquibase Change Types allows you to define these changes with XML, JSON, or YAML. For this walkthrough, we will use XML examples.

Creating changelog files manually

  1. Create a file in your Liquibase project directory called myChangeLog.xml
  2. For this example, enter the following information into the myChangeLog.xml file, then save your file:
<?xml version="1.0" encoding="UTF-8"?>  
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">
</databaseChangeLog>

Generating changelog files

If you have an existing database, you can generate a changelog file that reflects the current state of your database. For more information on how to generate a changelog, see the topics on the generate-changelog command and How to set up Liquibase with an Existing Project and Multiple Environments.

Step 2: Add a changeset

changesets are (units of change) that Liquibase can execute on a database. When adding a changeset, your change must be defined by both an id attribute and an author attribute. Using only an id attribute can cause accidental duplications when dealing with multiple developers and code branches. It is best practice to only include one change in each changeset.

See the Changeset topic for more information.

To add a changeset:

  1. Locate and open the myChangeLog.xml file.
  2. For this example, enter the following information into the myChangeLog.xml file, then save your file:
<?xml version="1.0" encoding="UTF-8"?>  
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext"
    xmlns:pro="http://www.liquibase.org/xml/ns/pro"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
        http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd
        http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd">

    <changeSet  id="1"  author="bob">  
        <createTable  tableName="department">  
            <column  name="id"  type="int">  
                <constraints  primaryKey="true"  nullable="false"/>  
            </column>  
            <column  name="name"  type="varchar(50)">  
                <constraints  nullable="false"/>  
            </column>  
            <column  name="active"  type="boolean"  defaultValueBoolean="true"/>  
        </createTable>  
    </changeSet>  

</databaseChangeLog>

Step 3: Run the changeset

When you add a changeset, Liquibase reads your list of changesets in order, then checks the DATABASECHANGELOG table for anything that was previously run.

To run the changeset:

  1. Open your terminal.
  2. Run one of the following commands:
    • Linux/Unix/Mac: LB_HOME/liquibase update
    • Windows: LB_HOME\liquibase.bat update

Note: In place of LB_HOME use the folder name where you extracted Liquibase.

Your database now contains a table called department.

Step 4: Check your database

To check your database:

  1. Open your terminal.
  2. Navigate to the folder where you placed your driver jar.
  3. Run: java -jar (driver-version.jar)

Note: Where (driver-version.jar) is listed, enter your driver name and version number. Example: java -jar h2-1.4.199.jar

If you use a Liquibase properties file, enter the JDBC URL, user name, and password. Notice that two tables were created:

  • DATABASECHANGELOG
  • DATABASECHANGELOGLOCK

The DATABASECHANGELOG table contains a list of all the changes that have been run against the database. The DATABASECHANGELOGLOCK table is used to make sure two machines don't attempt to modify the database at the same time.

See the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table topics for more information.

You can also check out the Migrating with SQL topic.

Summary

In this tutorial we covered:

  • Creating/Generating changelogs
  • Adding changeSets to your changelog
  • Running your changelog
  • Checking your Database