Normally rollback works by "rewinding" the database to a specified point.  All changesets deployed after that point are rolled back. 

Precise rollback targets specific changesets to modify. To use it, you need to do the following:

• Use the precise option on a rollback command. 

• Use search options to specify the changesets to modify

Use a preview to review the effects before running the rollback.

When the rollback is run, the specified changeset entries are removed from the DATABASECHANGELOG table.  

Syntax for Precise Rollback

The search options determine which changesets to modify. They select a list of changesets for the modify options to work on. 

Searches are not case-sensitive. 

• Multiple values in one statement are OR'ed together. 

• Multiple search option statements are ANDed together.

Search option statements take one or a comma-separated list of values. They are provided for changeset attributes as follows: 

• searchIds - id

• searchLabels - label

• searchContexts - context

• searchIgnore - ignore - true | false - Searches for false also return changesets where the ignore attribute is not set. true | false

• searchOrigFilePaths - origFilePath

• searchOrigFileNames - origFileName

• searchVersion - version, an integer. 

Conditions for Precise Rollback

Changesets must meet the following criteria when evaluated (previewed) for a precise rollback:

• Changesets must be deployed on the specified databases

• Transient scripts:

  • A rollback script is provided with the original SQL script

• Non-transient scripts: either condition must be true. 

  • A rollback script is provided with the original SQL script

  • The current version is equal or greater than 1 and the previous version of the changeset exists in the changelog. 

Additional Considerations

Normal rollbacks rewind the changelog to a defined point, undoing all changesets deployed after that point. 

Precise rollback removes individual changesets from the changelog.  Take care not to remove changesets that later deployments built on. 

For example:

1. Deploy a create table

2. Deploy a view on that table

If you now attempt to roll back only the changeset that created the table, then the view becomes invalid.  

Rolling Back Non-Transient or Rerunnable Changesets

Non-transient changesets are modified in place and versioned.

• Typically these are changes in stored logic (functions, procedures, triggers, views; Oracle packages and packagebodies). 

• Starting in version 4.37, they may also be identified by rerunnable=true. The rerunnable property is new.  

Requirements for Changesets to be Eligible for Rollback

You may roll back the current version (most recently deployed) to the previous version if its version number is equal or greater than 1. 

• You may perform multiple rollback operations as long as the version number is equal or greater than 1.

• You can roll back only one version at a time. 

If the search conditions for a precise rollback return more than one version of change, the most recent one is used. 

Rollback Operation

The rollback operation uses the rollback script for the current version if one is provided. If a rollback script is not provided, the operation attempts to locate the changeset for the previous version in the changelog and use it:

1. Check for a provided rollback script. If one exists, do the following:

   1. Run the rollback script

   2. If the rollback script is successful, delete the changeset for the current version from the DATABASECHANGELOG. 

2. If no rollback script exists, do the following:

   1. Check the changelog for the previous version of the changeset. Exit if it does not exist. 

   2. Run the previous version of the changeset.

   3. Remove the current version of the changeset from the DATABASECHANGELOG.

Rolling Back Transient Scripts

Precise rollback is available for transient scripts that do NOT use the convert_sql process. 

It is not available for the following:

• Workflow files for DDL/convert. This can include -cleanup, -ignore, -unignore and more.

• Scripts packaged as convert (flexible folder names)

  Note: DDL/convert files are supported in Liquibase Enterprise 8.3 and later if a rollback file is provided.

The original script may have created multiple changesets.

• A rollback script must exist. Exception: the change is one for which Datical provides an auto-rollback. See Auto-rollback Support by Database Object Change Type. 

During processing:

1. Assemble the changesets to roll back (based on search criteria).

2. Execute the rollback script on those changesets

3. Remove changeset entries from the changelog (DATABASECHANGELOG table)

Previewing a Precise Rollback

When you use the --preview argument, a preview report is generated but no changes are made. 

The preview report includes the following information:

• List of changesets affected - the list is generated by the search criteria. 

• Ineligible changesets - any changesets that cannot be rolled back

Logging

The log for the rollback is stored in the Reports directory with other reports for the dbdef (step).  See Available Log Files and Reports. 

Reports

The Rollback Report generates a log that describes what was rolled back when the rollback command is used.  The report can be produced in any of the following modes: LastDeploy, Precise, and Custom. When it is set, the report will be written to the directory specified or to the Reports directory by default if none is specified.

The report parameter can be specified while running the precise rollback command.
Example:
hammer rollback <dbdef> precise [--preview] [--report=<path>] [--<search-option>=<value>, ...]

Learn more about the Rollback Report here:https://datical-cs.atlassian.net/wiki/spaces/DDOC/pages/896570540