3 Ways to Run Liquibase

There are a few different 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 your use case.

In this article, we'll cover what you can do once you've created a database changelog file and you're ready to go:

1. Embed Liquibase into your product
2. Embed Liquibase into your build tools
3. Run Liquibase to generate SQL for review

Embed Liquibase into your product

Embedding Liquibase to automatically deploy on app startup is the easiest way to run Liquibase. Once you set up Liquibase to deploy on app 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.

When to use

• 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.

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.)

Embed Liquibase into your build tools

Since embedding Liquibase into the app doesn't work well for everyone, it's important to note that Liquibase can also be embedded into your build tools like Jenkins, Ant, Maven, and Gradle.

When to use

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.

How it works

For those who use Ant and Maven, Liquibase 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 deploy it to test environments.

For those who use Jenkins, there is a Liquibase shell script that ships with Liquibase that is equivalent to liquibase.bat.

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.

When to use

• 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

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.

Summing it up

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

• Some projects embed Liquibase into build tools for development and initial QA then updateSQL for final QA and production.
• Some projects automatically run Liquibase on app startup, but handle hotfixes through a more manual process.
• Other projects automatically run Liquibase on app startup 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.

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