rollback-on-error

Uses

--rollback-on-error is a Liquibase Secure command parameter that controls what happens when a deployment fails partway through. Set it to true, and Liquibase stops at the changeset that failed and rolls back the changesets that had already deployed successfully in the same operation, returning the database to the state it was in before the operation started. The default value is false, which leaves those successful changesets in place. The parameter is available on update, update-count, update-to-tag, update-one-changeset, and update-testing-rollback. With update-testing-rollback, it covers a changeset that fails during either update pass, but not a failure during the rollback pass. Commands that only generate SQL, such as update-sql, do not accept it.

The changeset that failed is not itself part of that rollback. Liquibase rolls back what deployed, not what did not.

A changeset with failOnError set to false does not count as a failure. Liquibase ignores the error and continues the deployment, so --rollback-on-error has nothing to roll back. That changeset is not recorded as deployed, so it runs again on the next update.

Note: The rollback is all or nothing. If any changeset deployed in the same operation cannot be rolled back, because it has no <rollback> block and its changes have no automatic rollback, as with a sql change, Liquibase rolls back none of them. The command exits with code 1 and reports that at least one changeset in this deployment does not contain a rollback, and every changeset that deployed before the failure stays in place. Changesets deployed by an earlier operation do not count.

Rolling back the failed changeset's own changes

A changeset can still commit part of its work before it fails, and when that happens the database no longer matches the state it was in before the operation started. Liquibase runs the failed changeset's own <rollback> block whenever any of these is true:

• runWith is set: The changeset runs through a native executor such as sqlplus or psql, which can report a failure after the database has already committed a statement.

• runInTransaction is false: Every statement in the changeset commits on its own, so the ones that ran before the failure are already durable.

• The changeset runs on Oracle: Oracle commits every DDL statement on its own, so a changeset with several DDL statements that fails on a later one has already committed the earlier ones.

In every other case the failure happened inside a transaction that was never committed, so the database already matches its pre-operation state and the block has nothing to undo. Liquibase reports that no deployed changesets were found to roll back, and does not run it. A changeset that has no <rollback> block is never rolled back this way, whichever of these conditions applies.

Note: In Liquibase Secure 6.0.0 on Oracle, a changeset that fails on its only statement also runs its own <rollback> block, even though nothing was committed. The rollback then tries to drop an object that was never created, and Liquibase reports that manual intervention is required to restore the database state. The database is unchanged, so no intervention is needed.

Note: Oracle is the only database Liquibase Secure 6.0.0 recognizes as committing DDL statements on their own. On other databases that behave this way, such as MySQL, MariaDB, Snowflake, and Databricks, a multi-statement changeset that fails after an earlier statement leaves the committed object in place, and a corrected re-run can fail because that object already exists.

Example: rollback-on-error

liquibase update --changelog-file=example-changelog.sql --rollback-on-error=true

Syntax

You can set this parameter in the following ways: