Liquibase Ant Tasks

Liquibase has a set of Ant tasks that provides

Installation

The Ant tasks require Ant 1.7.1 or higher. To include the tasks in your build, make sure Liquibase is on your Ant classpath and load it via the <taskdef> task:

<project name="Example" xmlns:liquibase="antlib:liquibase.integration.ant">
	<taskdef resource="liquibase/integration/ant/antlib.xml" uri="antlib:liquibase.integration.ant">
		<classpath path="path/to/liquibase/libs"/>
	</taskdef>
</project>

You can also place the Liquibase jar in your ANT_HOME/lib folder.

Concepts and Types

Database

All of the Liquibase Ant tasks are designed around the <database> type. This element configures the database connection and corresponding settings that Liquibase will use when accessing and updating the database. It is a required in all Liquibase Ant tasks.

Attribute	Description	Required
id	Unique identifier for this type instance, can be used to reference this type in tasks.	No
driver	The fully qualified class name of the JDBC driver.	Yes
url	The JDBC connection URL.	Yes
user	The username to the JDBC connection.	No
password	The password to the JDBC connection.	No
defaultSchemaName	The schema to use by default for managed database objects and Liquibase control tables.	No
defaultCatalogName	The catalog to use by default for managed database objects and Liquibase control tables.	No
outputDefaultSchema	Output the default schema name.	No; Default is true
outputDefaultCatalog	Output the default catalog name.	No; Default is true
liquibaseSchemaName	The schema name where the Liquibase tables will be located.	No
liquibaseCatalogName	The catalog name where the Liquibase tables will be located.	No
databaseClass	A fully qualified class name of a class that implements the `Database` interface. Used to add database types that are not officially supported by Liquibase.	No
databaseChangeLogTableName	Overrides the name of the DATABASECHANGELOG table.	No
databaseChangeLogLockTableName	Overrides the name of the DATABASECHANGELOGLOCK table.	No
liquibaseTablespaceName	The name of the tablespace where Liquibase tables are located.	No

	<liquibase:database id="my-database" driver="${db.driver}" url="${db.url}" user="${db.user}" password="${db.password}"/>

If you use more than one Liquibase task in your Ant build, you can create the <database> anywhere in your build, give it an id, and reference it using the databaseref attribute:

	<liquibase:database id="my-database" driver="${db.driver}" url="${db.url}" user="${db.user}" password="${db.pass}"/>
	
	<liquibase:update databaseref="my-database" changelogfile="path/to/changelog.xml"/>
	<liquibase:tag databaseref="my-database" tag="new-tag"/>

The <database> type also supports a nested element <connectionProperties> which allows users to specify custom JDBC connection properties to Liquibase:

<liquibase:database id="my-database" driver="${db.driver}" url="${db.url}" user="${db.user}" password="${db.pass}">
	<liquibase:connectionproperties>
		<liquibase:connectionproperty name="prop1" value="value1"/>
		<liquibase:connectionproperty name="prop2" value="value2"/>
		<propertyset>
			<propertyref prefix="liquibase"/>
		</propertyset>
	</liquibase:connectionproperties>
</liquibase:database>

Change Log Parameters

Liquibase change log files can have parameters that are dynamically substituted at runtime. All Liquibase Ant tasks support these parameters by way of the <changeLogParameters> element.

<liquibase:updateDatabase databaseref="my-database" changelogfile="/path/to/changelog.xml">
	<liquibase:changeLogParameters>
		<liquibase:changeLogParameter name="name1" value="value1"/>
		<liquibase:changeLogParameter name="name2" value="value2"/>
		<propertyset>
			<propertyref prefix="params"/>
		</propertyset>
	</liquibase:changeLogParameters>
</liquibase:updateDatabase>

Tasks

The following tasks are available in Ant:

Additional Liquibase commands are supported by the command line that are not supported by the Ant tasks.

Migrating From Legacy Tasks

Starting in Liquibase 3.3 the ant tasks were refactored, moving all of the database attributes out of the task and into its own type. The deprecated attributes will now log a warning message instructing callers of the deprecation. While backward compatibility exists, it is advised that users migrate their ant builds to use the new tasks.

In order to use the new Liquibase tasks, the <taskdef> needs to be redefined to use the antlib.xml file:

<project name="Example" xmlns:liquibase="antlib:liquibase.integration.ant">
	<taskdef resource="liquibase/integration/ant/antlib.xml" uri="antlib:liquibase.integration.ant">
		<classpath path="path/to/liquibase/libs"/>
	</taskdef>
</project>

Here is an example of a legacy update task:

<updateDatabase changeLogFile="${db.changelog.file}" 
				driver="${db.driver}"
				url="${db.url}"
				username="${db.username}"
				password="${db.password}"
				promptOnNonLocalDatabase="${prompt.user.if.not.local.database}"
				dropFirst="false"
				classpathref="classpath"/>

Here is what it looks like migrated to the new task structure:

<liquibase:updateDatabase changeLogFile="/path/to/changelog.xml" 
						  dropFirst="false" 
						  classpathref="classpath"
						  promptOnNonLocalDatabase="${prompt.user.if.not.local.database}">
	<liquibase:database driver="${db.driver}" 
						url="${db.url}" 
						user="${db.user}" 
						password="${db.password}"/>
</liquibase:updateDatabase>

Subscribe for email updates