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