Getting Started with Liquibase and Ant
Apache Ant is a Java library and command-line build tool for Java applications. Liquibase has a set of Ant tasks to automate your database changes at build time.
Note: Liquibase Ant tasks are implemented on the <database>
type. For more information about the attributes you can configure for the <database>
type, see Ant.
To use Liquibase with Ant:
- Ensure you have installed Ant. To verify that Ant is installed, run
ant -version
at the command prompt. You will get the output that looks likeApache Ant(TM) version 1.10.11 compiled on July 10 2021
. Liquibase Ant tasks require Ant 1.7.1 or later versions. - Create a Liquibase project directory to store all Liquibase and Ant files.
- Create an Ant build file called
build.xml
to specify your configuration settings with tasks, targets, and dependencies. Thebuild.xml
file also lets you define the needed Liquibase properties. See the example of the build.xml example with a basic configuration. - Include Liquibase in your Ant classpath and load it by adding the
<taskdef>
task in thebuild.xml
file: - Create a text file called
changelog.sql
in your Liquibase project directory. Liquibase also supports the.xml
,.yaml
, or.json
changelog formats. - Add changesets to your changelog file. Use the following examples depending on the format of the changelog you created:
- Execute the
updateDatabase
task by including the values in your Antbuild.xml
file: - Run the following in the CLI to implement the task and update your database:
<project basedir="the/runtime/location/of/Ant" name="example" xmlns:liquibase="antlib:liquibase.integration.ant">
<taskdef resource="liquibase/integration/ant/antlib.xml" uri="antlib:liquibase.integration.ant">
<classpath path="the/path/to/the/liquibase.jar;the/path/to/the/driver.jar" />
</taskdef>
</project>
Tip: You can put the Liquibase JAR in your ANT_HOME/lib
folder.
XML example:
<?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="Liquibase">
<createTable tableName="test_table">
<column name="test_id" type="int">
<constraints primaryKey="true"/>
</column>
<column name="test_column" type="varchar"/>
</createTable>
</changeSet>
</databaseChangeLog>
SQL example:
-- liquibase formatted sql
-- changeset liquibase:1
CREATE TABLE test_table (test_id INT, test_column VARCHAR, PRIMARY KEY (test_id))
YAML example:
databaseChangeLog:
- changeSet:
id: 1
author: Liquibase
changes:
- createTable:
columns:
- column:
name: test_column
type: INT
constraints:
primaryKey: true
nullable: false
tableName: test_table
JSON example:
{
"databaseChangeLog": [
{
"changeSet": {
"id": "1",
"author": "Liquibase",
"changes": [
{
"createTable": {
"columns": [
{
"column":
{
"name": "test_column",
"type": "INT",
"constraints":
{
"primaryKey": true,
"nullable": false
}
}
}]
,
"tableName": "test_table"
}
}]
}
}]
}
<target name="updateDatabase" depends="prepare">
<liquibase:updateDatabase changeLogFile="com/example/changelog.sql">
<liquibase:database driver="org.postgresql.Driver"
url="${db.url}"
user="${db.user}"
password="${db.pass}"/>
</liquibase:updateDatabase>
</target>
ant -f build.xml updateDatabase
After your first update, you will see a new table along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table added to the database.
build.xml
example:
<project name="liquibase-test" basedir="." xmlns:liquibase="antlib:liquibase.integration.ant">
<!-- The "prepare" target configures the classpath and properties Liquibase will use during task execution.-->
<!-- Liquibase targets must include a "depends" attribute to ensure the prepare target executes before the Liquibase task.-->
<target name="prepare">
<taskdef resource="liquibase/integration/ant/antlib.xml" uri="antlib:liquibase.integration.ant">
<classpath path="lib\liquibase.jar;lib\postgresql-42.2.18.jar"/>
</taskdef>
<!-- set global properties for Liquibase Tasks -->
<!-- Liquibase properties can be referenced using a "${}" string replacement within a liquibase.database change.-->
<property name="db.url" value="jdbc:postgresql://localhost:8080/example"/>
<property name="db.user" value="user"/>
<property name="db.pass" value="password"/>
<property name="db.driver" value="org.postgresql.Driver"/>
<!-- Alternatively, a database instance can be created and referenced with databaseref in a Liquibase task.-->
<liquibase:database id="my-database" url="${db.url}" user="${db.user}" password="${db.pass}" driver="org.postgresql.Driver"/>
</target>
<!-- Liquibase Tasks -->
<!-- The updateDatabase target shows using the individual database connection properties.-->
<target name="updateDatabase" depends="prepare">
<liquibase:updateDatabase changeLogFile="com/example/changelog.sql">
<liquibase:database driver="${db.driver}" url="${db.url}" user="${db.user}" password="${db.pass}"/>
</liquibase:updateDatabase>
</target>
</project>
Related links
Last update:
May 23, 2023
Created: May 23, 2023
Created: May 23, 2023