Liquibase Rollback Workflow

Liquibase provides commands to allow you to undo changes you have made to your database, either automatically or with a custom rollback command. The intention of a rollback script is to return the database to a previous specified point in time.

Note: Rollback support is available in command line, Ant, and Maven.

There are three rollback modes:

Command Description
rollback <tag> command This command will revert all changes made to the database after the specified tag. It is used when you want to undo a series of changes related to a specific tag such as a numbered release.
rollbackToDate command

This command is used to revert all changes made to the database from the current date to the date and time you specify. There are several ways to revert your changes with the rollbackToDate command.

There are three options: You can use YYYY-MM-DD, HH:MM:SS, or YYYY-MM-DD'T'HH:MM:SS formats to specify the rollback date, time, or date + time. You can also specify date or time only.

Examples: rollbackToDate YYYY-MM-DDrollbackToDate HH:MM:SSrollbackToDate YYYY-MM-DD’T’HH:MM:SS

rollbackCount <value> command This command is used to roll back a specified number of changesets, where <value> is the number of changesets you want to revert sequentially on your database. The command will rollback the changes sequentially starting with the most recent changes.

Liquibase Pro rollback commands

Liquibase Pro contains additional built in commands that allow you to perform targeted rollback tasks.

Command Description
rollbackOneChangeSet command This command will revert one non-sequential changeset made during a previous change to the database without affecting any other changes made to your database.
rollbackOneUpdate command This command will revert all changesets related to a specific deploymentId that was made during a previous database change. The command will undo a series of changes made to the database during a specific deployment and revert those changesets to their previous state without affecting any other changes made to the database.

Validating rollbacks

Rollback scripts are one of the most difficult aspects of application development to create and maintain, especially when data is modified.

  • If the database change is simple such as adding a new index, or an update to a stored procedure, then the rollback is straight forward.

  • Rolling back complex changes that involve structural changes and data migrations are much more difficult.

So before performing a rollback, it is important to validate the changes Liquibase will run prior to making the change to the database. These two commands help in validating and testing rollbacks.

Command Description
updateTestingRollback command This command is used to test rollback functionality when deploying changesets in your changelog sequentially. It tests the rollback by deploying all pending changesets, executing a sequential rollback in reverse order for the changesets that were deployed, then running the update again.
futureRollbackSQL command Produces the raw SQL Liquibase would use to revert changes associated with undeployed changesets. Used when auditors need to verify that all database changes have a rollback.

Rollbacks are also validated with the help of SQL helper commands.

Command Description
rollbackSQL <tag> command This helper command is used in conjunction with the rollback<tag> command to inspect the SQL Liquibase will use to revert changes associated with the tag you specify.
rollbackToDateSQL command This helper command is used in conjunction with the rollbackToDate command to inspect the SQL that Liquibase will run when using the rollbackToDate command.
updateCountSQL <value> command This helper command is used in conjunction with the rollbackCount <value> command to inspect the SQL Liquibase will use to rollback changes based on the value specified.
Pro Command Description
rollbackOneChangeSetSQL command This helper command is used in conjunction with the rollbackOneChangeSet command to inspect the SQL Liquibase will use to rollback changes based on the specified changeset.
rollbackOneUpdateSQL command This helper command is used in conjunction with the rollbackOneUpdate command to inspect the SQL Liquibase will run to revert all changesets associated with the deploymentId specified in the rollbackOneUpdate command.

Rollback test cycle

Rollback scripts are like any other change. They need to be tested just like application code so we know they work as designed.

You will need to carefully test your rollback scripts. This includes determining who will test the rollback script, how and when they will be tested.

A complete test cycle should include:

  1. Deploying all changes to the database and validating that they were deployed.

  2. Rolling back all changes to the database, validate that all changes were reversed, and verification that the database was brought back to the previous state.

  3. Redeploy all changes to the database. This is required to verify that the rollback did not miss any changes that could impact a future deployment.

Creating rollback statements

Many Change Types such as create table, rename column, and add column can automatically create rollback statements. If your changelog contains only statements that fit into this category, your rollback commands will be generated automatically.

Other Change Types such as drop table and insert data have no corresponding rollback commands that can be automatically generated. In these cases, and cases where you want to override the default generated rollback commands, you can specify the rollback commands via the tag within the changeset tag. If you do not want anything done to undo a change in rollback mode, use an empty rollback tag.

To determine if Liquibase can automatically rollback a specific change type, check the Change Types documentation and navigate to the Database Support section to determine whether auto rollback is available for your database platform.

Note: Automatic rollback is NOT supported for formatted SQL changesets. You should add custom rollback statements to formatted SQL changesets if you want to use rollback commands.