Need Liquibase® support? Liquibase Pro is now available! Try it out free.
2018 XML Announcement
Achieving Continuous Delivery at Fidelity Investments with IBM UrbanCode and Datical

Liquibase Quick Start


This Quick Start provides a brief orientation to Liquibase, and addresses three key topics:

The quick start does not cover every feature available in Liquibase, and is instead focused on ensuring that you understand the core concepts and are able to address basic use cases.

Database Change Management: State and Migration approaches

There are two approaches for managing database changes. The first approach is state-based (or declarative) – in which the desired state of the database is defined. A tool that can compare (or diff) the target environment against the defined desired state is used to generate migration scripts that allow the target environment to match the declared state. The alternative approach is migration-based (or imperative) – in which the specific migrations for altering the state of a database are described. A tool capable of explicitly tracking and ordering the individual migrations and deploying the migrations that have not yet been deployed to the target environment is used to get the target database properly migrated.

While Liquibase is capable of comparisons (or diffs), it is fundamentally a migration-based solution. The diff capability in Liquibase is only meant to assist with onboarding new projects and with sanity checking that database migrations have been properly applied. As a migration-based solution, Liquibase can easily:

  • Track all proposed database changes, including the specific order they need to be deployed in, who proposed/authored the change, and record the purpose of the change (as a comment)
  • Clearly answer whether a database change has or has not been deployed to a database. Effectively, Liquibase is able to “version” each database
  • Deterministically deploy changes to a database, including promoting a database to a specific “version”
  • Prevent users from modifying changes that have already been deployed to a database and requiring that they either deliberately rework the deployed change or roll-forward

How Liquibase Works

At its core, Liquibase relies on a simple mechanism to track, version, and deploy changes:

  • Liquibase uses a change log (which is a ledger of changes) to explicitly list database changes in a specific order. Each change in the change log is a “change set”. Change logs can be arbitrarily nested to aid in organization and management of database migrations.
    • Note: It is a best practice to ensure that each change set is as atomic a change as possible to avoid failed statements from leaving the database in an unknown state; however, it is possible to treat a large SQL script as a single change set.
  • Liquibase uses a tracking table (specifically called ‘DATABASECHANGELOG’) which resides on each database and which tracks which change sets in the change log have been deployed.
    • Note: if there is no tracking table on a database that Liquibase is acting upon, the Liquibase will create a tracking table.
    • Note: To assist with projects where you are not starting with a blank database, Liquibase has a feature to generate a change log to represent the current state of the database schema.

With the ledger and the tracking table, Liquibase is able to:

  • Track and version database changes – Users know exactly what changes have been deployed to the database and what changes have not yet been deployed.
  • Deploy changes – specifically, by comparing what is in the ledger against what is in the tracking table, Liquibase is able to deploy only the changes that have not yet been deployed previously to the database.
    • Note: Liquibase has advanced features such as contexts, labels, and preconditions to precisely control when and where changeSets are deployed.

Tutorials: Track, Version, and Deploy Database Changes with Liquibase

When working with Liquibase, changes can either be defined with the Liquibase functions or with SQL. Importantly, these modes are not mutually exclusive, and can be used in conjunction, providing considerable flexibility in how database changes are defined and deployed. For changes defined with Liquibase functions, Liquibase generates SQL appropriate for the target database. This can be helpful when:

  • Supporting multiple different database backends. This is a common use case if you are a software vendor looking to avoid writing the same database migrations simply to support different database platforms.
  • Enabling developers who are not proficient or experienced with SQL to define database changes. Instead of SQL, the database migrations can be defined in XML, JSON, or YAML.
  • Standardizing database changes. Liquibase will generate syntactically and stylistically consistent SQL, ensuring, as an example, that all ‘CREATE TABLE’ migrations have the same style and pattern.

Alternatively, Liquibase works directly with user provided database migrations. This can be helpful when:

  • Making changes that are not Liquibase functions. Changes that are custom or specific to a database – for example, Oracle Nested Tables – are not typically Liquibase functions.
  • Enabling developers highly proficient in SQL who strongly prefer working directly with SQL. It’s a common misconception that Liquibase only supports “XML database migrations”. The reality is that Liquibase can absolutely support plain SQL scripts!

Note: Liquibase Pro adds change types for defining procedural database code to Liquibase functions. However, unlike other changes that are Liquibase functions, these procedural database code changes, such as “CREATE FUNCTION”, require database platform specific SQL (for example, on Oracle, the change would require PL/SQL). These new change types can be helpful in providing better visibility into database-specific changes from directly inspecting the change log.

Tutorial Setup

Before attempting any of the step-by-step tutorials, please prepare your environment with the setup instructions.

Step 1: Download and Extract Liquibase

  1. Download Liquibase. Visit the download page to get the latest binary.
  2. After downloading the *.zip or *.tar.gz, extract the contents into a folder.

Step 2: Install Java

  1. Java is a required dependency. Install Java if it is not already installed.
    • Note: You can download and use the OpenJDK. Be sure to configure your path and environment variable properly.
  2. Validate that you have a working java version.
    • On the command line, execute:
      java -version
    • Ensure that it runs successfully and displays your installed Java version.

Step 3: Download the H2 JDBC Driver

  1. The tutorials make use of an H2 database. You will need to download the H2 JDBC driver, which can be found here.
  2. Copy the h2*.jar file into the directory that you extracted the Liquibase *.zip or *tar.gz

Step 4: Setup

  1. The tutorials use the CLI. While it is possible to pass all required parameters, such as the JDBC driver and database URL, it is much easier to configure a file to save time and effort.
  2. Create a Add the following content to the file and save it in the directory that you extracted the Liquibase *.zip or *.tar.gz.
    driver: org.h2.Driver
    classpath: ./h2-1.4.199.jar
    url: jdbc:h2:file:./h2tutorial
    username: admin
    password: password
    changeLogFile: myChangeLog.xml
    • Note: Be sure to use the actual version of the h2*.jar file that you copied into the extracted Liquibase directory!

That is all! You are now setup to start one of the tutorials!

Tutorial: Getting Started Using SQL Scripts

This tutorial is ideal for those comfortable and familiar with SQL. The tutorial starts with a blank database and guides you through the process of using Liquibase to track, version, and deploy SQL scripts located in a specific folder.

Start with SQL Scripts

Tutorial: Getting Started Using Liquibase Functions

This tutorial uses Liquibase functions. Instead of working with SQL, changes will be defined in XML. Liquibase will generate SQL based on the changeSet(s) defined and will deploy that to target databases. All migrations are tracked and ordered explicitly in the changeLog.

Start with Liquibase Functions

Missing, incomplete or wrong information? Please send a pull request