Introduction to Liquibase Rollback

1. Overview

In our previous article, we showed Liquibase as a tool for managing database schemas and data.

In this article, we’re going to look more into the rollback feature – and how we can undo a Liquibase operation.

Naturally, this is a critical, feature of any production-grade system.

2. Categories of Liquibase Migrations

There are two categories of Liquibase operations, resulting in a different generation of a rollback statement:

• automatic, where migration can deterministically generate steps required for rolling back
• manual, where we need to issue a rollback command because migration instruction cannot be used to identify the statement deterministically

For example, the rollback of a “create table” statement would be to “drop” the created table. This can be determined without a doubt, and therefore the rollback statement can be autogenerated.

On the other hand, the rollback statement for a “drop table” command is not possible to be determined. It is not possible to determine the last state of the table, and therefore the rollback statement can’t be autogenerated. These types of migration statements require a manual rollback instructions.

3. Writing a Simple Rollback Statement

Let’s write a simple changeset which will create a table when executed and add a rollback statement to the changeset:

<changeSet id="testRollback" author="baeldung">
    <createTable tableName="baeldung_turorial">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
        <column name="author" type="varchar(36)"/>
    </createTable>
    <rollback>
        <dropTable tableName="baeldung_test"/>
    </rollback>
</changeSet>

The above example falls under the first category mentioned above. It will create a rollback statement automatically if we do not add one. But we can override the default behavior by creating our rollback statement.

We can run the migration using the command:

mvn liquibase:update

After the executing we can rollback the action using:

mvn liquibase:rollback

This executes the rollback segment of the changeset and should revert the task completed during the update stage. But if we issue this command alone, the build will fail.

The reason for that is – we do not specify the limit of rollback; the database will be completely wiped out by rolling back to the initial stage. Therefore it’s mandatory to define one of the three constraints below to limit the rollback operation when the condition is satisfied:

• rollbackTag
• rollbackCount
• rollbackDate

3.1. Rolling Back to a Tag

We can define a particular state of our database to be a tag. Therefore, we can reference back to that state. Rolling back to the tag name “1.0” looks like:

mvn liquibase:rollback -Dliquibase.rollbackTag=1.0

This executes rollback statements of all the changesets executed after tag “1.0”.

3.2. Rolling Back by Count

Here, we define how many changesets we need to be rolled back. If we define it to be one, the last changeset execute will be rolled back:

mvn liquibase:rollback -Dliquibase.rollbackCount=1

3.3. Rolling Back to Date

We can set a rollback target as a date, therefore, any changeset executed after that day will be rolled back:

mvn liquibase:rollback "-Dliquibase.rollbackDate=Jun 03, 2017"

The date format has to be an ISO data format or should match the value of DateFormat.getDateInstance() of the executing platform.

4. Rollback Changeset Options

Let’s explore what are the possible usages of rollback statement in changesets.

4.1. Multistatement Rollback

A single rollback tag may enclose more than one instruction to be executed:

<changeSet id="multiStatementRollback" author="baeldung">
    <createTable tableName="baeldung_tutorial2">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
    </createTable>
    <createTable tableName="baeldung_tutorial3">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
    </createTable>
    <rollback>
        <dropTable tableName="baeldung_tutorial2"/>
        <dropTable tableName="baeldung_tutorial3"/>
    </rollback>
</changeSet>

Here we drop two tables in the same rollback tag. We can split the task over multiple statements as well.

4.2. Multiple Rollback Tags

In a changeset, we can have more than one rollback tags. They are executed in the order of appearance in changeset:

<changeSet id="multipleRollbackTags" author="baeldung">
    <createTable tableName="baeldung_tutorial4">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
    </createTable>
    <createTable tableName="baeldung_tutorial5">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
    </createTable>
    <rollback>
        <dropTable tableName="baeldung_tutorial4"/>
    </rollback>
    <rollback>
        <dropTable tableName="baeldung_tutorial5"/>
    </rollback>
</changeSet>

4.3. Refer Another Changeset for Rollback

We can refer to another change set, possibly the original changeset if we are going to change some details of the database. This will reduce the code duplication and can correctly revert the done changes:

<changeSet id="referChangeSetForRollback" author="baeldung">
    <dropTable tableName="baeldung_tutorial2"/>
    <dropTable tableName="baeldung_tutorial3"/>
    <rollback changeSetId="multiStatementRollback" changeSetAuthor="baeldung"/>
</changeSet>

4.4. Empty Rollback Tag

By default, Liquibase tries to generate a rollback script if we have not provided. If we need to break this feature, we can have empty rollback tag so that rollback operation is not get reverted:

<changeSet id="emptyRollback" author="baeldung">
    <createTable tableName="baeldung_tutorial">
        <column name="id" type="int"/>
        <column name="heading" type="varchar(36)"/>
        <column name="author" type="varchar(36)"/>
    </createTable>
    <rollback/>
</changeSet>

5. Rollback Command Options

Apart from rolling back a database to a previous state, Liquibase can be used in many different ways. Those are, generate the rollback SQL, create future rollback script, and finally, we can test the migration and rolling back, both in one step.

5.1. Generate Rollback Script

Same as rolling back, we have three options in hand for generating rollback SQL. Those are:

• rollbackSQL <tag> – a script for rollbacking the database to the mentioned tag
• rollbackToDateSQL <date/time> – an SQL script to rollback the database to the state as of the mentioned date/time
• rollbackCountSQL <value> – an SQL script to rollback the database to the state mentioned by number of steps before

Let’s see one of the examples in action:

mvn liquibase:rollbackCountSQL 2

5.2. Generate Future Rollback Script

This command generates the required rollback SQL commands to bring the database to the current state from the state, at which changesets eligible to run at the moment, have completed. This will be very useful if there is a need to provide a rollback script for a change we are about to perform:

This will be very useful if there is a need to provide a rollback script for a change we are about to perform:

mvn liquibase:futureRollbackSQL

5.3. Run Update Testing Rollback

This command executes the database update and then rolls back the changesets to bring the database to the current state. Both future rollback and update testing rollback does not alter the current database after the executing is finished. But update testing rollback performs the actual migration and then rolls it back.

This can be used to test te execution of update changes without permanently changing the database:

mvn liquibase:updateTestingRollback

6. Conclusion

In this quick tutorial, we explored some command line and changeset features of the Liquibase rollback functionality.