3 Ways to Run Liquibase

There are three primary ways to run Liquibase. Each application and project team has different needs so the best way to run Liquibase depends on what works best for you. Many teams may even use a combination of all three methods. In this article, we’ll cover what you can do once you’ve created a database changelog file and you’re ready to go:

  • Run Liquibase automatically and deploy on startup
  • Run Liquibase manually, as needed
  • Run Liquibase with plain SQL

Automatically Deploy Liquibase on Startup

This is the easiest way to run Liquibase. Once you set up Liquibase to deploy on startup, your database state will always match what your code expects.

Liquibase uses a DATABASECHANGELOGLOCK table to ensure that only one instance of Liquibase runs at a time. Even if you have multiple servers pointing to the same database or a cluster of servers all coming online at the same time and all automatically running Liquibase, you don’t have to worry. The lock table ensures that they will not all try to update the database concurrently and cause problems.

How it Works

Liquibase ships with two hooks to automatically update your database on startup: a servlet listener and a Spring bean.

If neither of those hooks fit with your application, you can always call the Liquibase Java API directly.

The most straightforward way of running Liquibase directly looks like this:

java.sql.Connection connection = openConnection(); //your openConnection logic here
Database database = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(new JdbcConnection(connection));
Liquibase liquibase = new liquibase.Liquibase("path/to/changelog.xml", new ClassLoaderResourceAccessor(), database);
liquibase.update(new Contexts(), new LabelExpression());

This code creates an instance of the liquibase.Liquibase façade and run the update() method which simply updates the database to match the passed changelog. (There are many other methods on the Liquibase façade which can also be used if you are looking to automate Liquibase in different ways.)

When to Use Automatic Deployment

In environments where you have less control over the deployment process
Create an automated release process from code check in through live production. We’ve seen this method used for web applications that use Continuous Delivery to release multiple times per day.

In environments where you want a transparent database management process
Provide visibility into database management for packaged applications that are shipped to customers.

Manually Deploy Liquibase

Since automatic database updates don’t work well for everyone, it’s important to note that Liquibase can also be executed on demand.

How it Works

Liquibase ships with a command line application that supports both Windows and Linux. For those who use Ant and Maven, it also ships with an Ant task and a Maven goal. These interfaces allow you to execute Liquibase commands whenever you need them, without being tied to application startup.

One common use for the Ant and/or Maven interface is to integrate Liquibase into your build process which allows you to catch errors in your changelog earlier. This also gives you the ability to run automated tests against a database. Developers can run the same tasks against their local environment for initial development and for fixing issues.

Pro Tip: Contexts allow users to embed test data in the changelog and only deploying it to test environments.

When to Use Manual Deployment

When you want to use Ant and Maven
When you have a more complex release process designed to eliminate downtime

Example: If you make your database changes compatible with the existing codebase (i.e., no DROP commands), you can run Liquibase update while the old version of your site is still running. Once it has updated successfully, you can begin a staged rollout of new code across your cluster.

Using Liquibase to Generate the SQL that Your DBAs Want to Run

Liquibase supports an updateSQL mode in the command line, as well as in Ant and Maven interfaces.

How it Works

When running updateSQL, Liquibase simply outputs the SQL it would have normally run. The output includes both the SQL to update your database and also the SQL to keep the DATABASECHANGELOG table up to date. Inspect the output as needed and then execute it through whatever database tools you prefer. After running the SQL, your database will be in the correct state and Liquibase will know what was run and so future updateSQL calls will include only new changeSets.

When to use SQL Execution with Liquibase

When it’s important to you to know exactly what is being done to your database
“Just give me the SQL and I’ll do it myself!” Manual updates with Liquibase allow you to control when the database is updated, but not what is actually executed.

When company policies prevent you from using Liquibase in certain environments

Mix and Match

All the methods described above can be mixed and matched as needed to handle whatever schema management needs you may have.

When to Mix and Match

  • Some projects use automatic deployment for development and initial QA then updateSQL for final QA and production.
  • Some projects automatically run Liquibase on startup, but handle hotfixes through a more manual process.
  • Other projects automatically run Liquibase all the way through production but the executed SQL is automatically saved and monitored by DBAs throughout the release progression to ensure nothing unexpected is happening.

Summing it up

No matter what your schema deployment needs are, you can find a way to manage them with Liquibase.

If you have any questions about how to get Liquibase up and running for your application, support is now available through Liquibase Pro.