Getting Started with Liquibase and Gradle
Using the Liquibase Gradle plugin helps to manage database scripts, build and automate your software processes. When Gradle applies the plugin to the target, it creates a Gradle task for each command supported by Liquibase. To see the list of those tasks, run the gradle tasks
command.
To use Liquibase and Gradle:
- Create a text file called
build.gradle
in your project folder or use the existingbuild.gradle
file. - Add the following section to your
build.gradle
file to include theliquibase
plugin into Gradle builds: - Add the
dependencies
section to include files on which Liquibase will depend to run commands. The plugin needs to find Liquibase when it runs a task, and Liquibase needs to find database drivers, changelog parsers, and other files on the classpath. When addingliquibaseRuntime
dependencies to thedependencies
section in thebuild.gradle
file, include the Liquibase value along with your database driver: - Create a text file in your application directory and name it
changelog.sql
. Liquibase also supports the XML, YAML, and JSON changelog formats. Another way to use Liquibase and Gradle is with thechangelog.groovy
file. - Add changesets to your changelog file. Use the following examples depending on the format of the changelog you created:
- Set the following Liquibase properties in your
build.gradle
file: - Do your first update by adding the task section to the
build.gradle
file: - Run the
gradle build
command, and then run the following: - [Optional] Do your first rollback by using the
rollback-count
command: - Check the changes by inspecting your database or running the status command.
plugins {
id 'org.liquibase.gradle' version '2.2.4'
}
The following legacy plugin application is also available to use:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "org.liquibase:liquibase-gradle-plugin:2.2.0"
}
}
apply plugin: 'org.liquibase.gradle'
dependencies {
liquibaseRuntime 'org.liquibase:liquibase-core:4.24.0'
liquibaseRuntime 'org.liquibase:liquibase-groovy-dsl:2.1.1'
liquibaseRuntime 'info.picocli:picocli:4.7.5'
liquibaseRuntime 'org.yaml:snakeyaml:1.33'
liquibaseRuntime 'mysql:mysql-connector-java:5.1.34'
}
apply plugin: "org.liquibase.gradle"
Replace org.liquibase:liquibase-core:4.24.0
and mysql:mysql-connector-java:5.1.34
with your values. If you use Groovy scripts for database changes, the example code includes the Liquibase Groovy DSL dependency, which parses changelogs written in a Groovy DSL. You do not need to add org.liquibase:liquibase-groovy-dsl:2.1.1
if you do not use the Groovy changelog format. For more information, see Step 4.
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"
}
}]
}
}]
}
Groovy example:
databaseChangeLog = {
changeSet(id: '1', author: 'liquibase') {
createTable(tableName: 'test_table') {
column(name:'test_id', type="int") {
constraints(primaryKey: true)
}
column(name:'test_column', type="varchar")
}
}
}
liquibase {
activities {
main {
changelogFile "../changelog.sql"
url "mysql://localhost:3306/testdatabase"
username "username"
password "password"
}
}
}
Note: Replace the values from the example with your values.
Tip: To store other Liquibase properties in a file instead of passing them at runtime, you can continue specifying the properties in the build.gradle
file or create a new text file called liquibase.properties
and set them there. If you create a Liquibase properties file, specify propsFile "../<liquibase.properties>"
in the main section of the build.gradle
file, where <liquibase.properties>
represents the name of the Liquibase properties file. For more information, see Create and Configure a liquibase.properties File.
task('deploy changeLog') {
doFirst() {
liquibase {
activities {
main {
changeLogFile System.properties.liquibaseChangeLogFile
contexts System.properties.liquibaseContexts
}
}
}
}
}
update.dependsOn(deploy)
gradle update
After your first update, you will see a new table along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table added to the database.
gradle build
gradle rollbackCount -PliquibaseCommandValue=1
Note: You can also specify the command value in the build.gradle
file or use other rollback
commands: rollback, rollback-to-date, rollback-one-changeset, rollback-one-update.
Tip: Automatic rollback is not supported for formatted SQL changesets. You need to add custom rollback statements to formatted SQL changesets if you want to use rollback commands:
-- changeset liquibase:1
create table test_table ( id int primary key, name varchar(255) );
-- rollback drop table test_table;
Related links
Created: May 23, 2023