For an example of how to use this plugin, see the
Liquibase Workshop repo.
That project contains a build.gradle
showing exactly how to configure the
plugin, and an example directory setup as well.
###September 10, 2014 This plugin is designed to be a wrapper for the Liquibase project, so it creates tasks to match the various Liquibase commands. This can cause conflicts with tasks that other plugins create, so we've added the ability to add a prefix to all the tasks this plugin creates. See the Usage section for more details.
###June 15, 2014 We are proud to announce the long awaited release of version 1.0.0 of the Gradle Liquibase Plugin. Version 1.0.0 uses version the latest release of Liquibase (3.1.1), and it appears to work fine with both Gradle 1.x releases as well as the upcoming Gradle 2.0 release.
Tim Berglund has asked me to take on the continued maintenance of this plugin,
so I've had to change the maven group ID to one for which I have permission to
publish on Maven Central. Going forward, this plugin will be available under
the net.saliman
group id. The artifact ID, gradle-liquibase-plugin
will remain the same.
My thanks to Tim for the opportunity to help out with this great plugin.
Steve Saliman
Version 1.0.0 of the Liquibase plugin uses Liquibase 3, instead of Liquibase 2, and several things have been deprecated from the Groovy DSL to maintain compatibility with Liquibase XML. A list of deprecated items can be found in the README for the Groovy DSL project in the Usage section. To upgrade to version 1.0.0, we strongly recommend the following procedure:
-
Make sure all of your Liquibase managed databases are up to date by running
gradle update
on them before upgrading to version 1.0.0 of the Liquibase plugin. -
Create a new, throw away database to test your Liquibase change sets. Run
gradle update
on the new database using the latest version of the Liquibase plugin. This is important because of the deprecated items in the Groovy DSL, and because there are some subtle differences in the ways the different Liquibase versions generate SQL. For example, adding a default value to a boolean column in MySql usingdefaultValue: "0"
worked fine in Liquibase 2, but in Liquibase 3, it generates SQL that doesn't work for MySql -defaultValueNumeric: 0
needs to be used instead. -
Once you are sure all of your change sets work with the latest Liquibase plugin, clear all checksums that were calculated by Liquibase 2 by running
gradle clearChecksums
against all databases. -
Finally, run
gradle changeLogSync
on all databases to calculate new checksums.
Configuring the plugin in version 1.0.0 is different from previous versions.
The Liquibase configuration now goes in a liquibase
block of the
build.gradle file instead of separate blocks. The changelogs
and
database
closures have been merged into a single activities
closure
with methods instead of variables. The defaultDatabase
and
defaultChangelogs
variables have been replaced with the optional
runList
variable.
For example:
changelogs {
main {
file = file('src/main/db/changelogs.groovy')
}
}
databases {
myDB {
url = 'jdbc:mysql://localhost:3306/my_db'
username= 'myusername'
password = 'mypassword'
}
defaultDatabase = databases.myDB
defaultChangeLogs = changelogs
Became:
liquibase {
activities {
main {
changeLogFile 'src/main/db/changelogs.groovy'
url 'jdbc:mysql://localhost:3306/my_db'
username 'myusername'
password 'mypassword'
}
}
}
The Liquibase plugin uses the Groovy DSL syntax intended to mirror the Liquibase XML syntax directly, such that mapping elements and attributes from the Liquibase documentation to Groovy builder syntax will result in a valid changelog. Hence this DSL is not documented separately from the Liquibase XML format. However there are some minor differences or enhancements to the XML format, and there are some gaping holes in Liquibase's documentation of the XML. Those holes are filled, and differences explained in the documentation on the Groovy Liquibase DSL project page.
The Liquibase plugin is meant to be a light weight font end for the Liquibase
command line utility. When the liquibase plugin is applied, it creates a
Gradle task for each command supported by Liquibase. The
Liquibase Documentation
describes what each command does and what parameters each command uses. If you
want to prefix each task to avoid task name conflicts, set a value for the
liquibaseTaskPrefix
property. This will tell the liquibase plugin to
capitalize the task name and prefix it with the given prefix. For example,
if Gradle is invoked with -PliquibaseTaskPrefix=liquibase
, or you put
liquibaseTaskPrefix=liquibase
in gradle.properties
then this
plugin will create tasks named liquibaseUpdate
, liquibaseTag
, etc.
Parameters for the commands are configured in the liquibase
block inside
the build.gradle file. This block contains a series of, "activities", each
defining a series of Liquibase parameters. Any method in an "activity" is
assumed to be a Liquibase parameter. The liquibase
block also has an
optional "runList", which determines which activities are run for each task. If
no runList is defined, the Liquibase Plugin will run all the activities. NOTE:
the order of execution when there is no runList is not guaranteed.
Example:
Let's suppose that for each deployment, you need to update the data model for
your application's database, and wou also need to run some SQL statements
in a separate database used for security. The liquibase
block might
look like this:
liquibase {
activities {
main {
changeLogFile 'src/main/db/main.groovy'
url project.ext.mainUrl
username project.ext.mainUsername
password project.ext.mainPassword
}
security {
changeLogFile 'src/main/db/security.groovy'
url project.ext.securityUrl
username project.ext.securityUsername
password project.ext.mainPassword
}
}
runList = project.ext.runList
}
Some things to keep in mind when setting up the liquibase
block:
-
We only need one activity for each type of activity. In the example above, the database credentials are driven by build properties so that the correct database can be specified at build time so that you don't need a separate activity for each database.
-
By making the value of
runList
a property, you can determine the activities that get run at build time. For example, if you didn't need to run the security updates in the CI environment, you could typegradle update -PrunList=main
For environments where you do need the security updates, you would usegradle update -PrunList='main,security'
This use of properties is the reason the runList is a string and not an array. -
The methods in each activity are meant to be pass-throughs to Liquibase. Any valid Liquibase command parameter is a legal method here. For example, if you wanted to increase the log level, you could add
logLevel debug
to the activity. -
In addition to the command pass-through methods of an activity, there is a
changeLogParameters
method. This method takes a map, and is used to setup token substitution in the changeLogs. See the Liquibase documentation for more details on token substitution. -
Some Liquibase commands like
tag
androllback
require a value, in this case a tag name. Since the value will likely change from run to run, the command value is not configured in theliquibase
block. To supply a command value, add-PliquibaseCommandValue=<value>
to the gradle command.