Check Chains

Note: This is a Liquibase Pro feature, so you need a Liquibase Pro License Key to use it.

Check Chains allow users to link multiple checks together and act as one Quality Check. Check Chains help ensure policies are followed and allow a job to be stopped if compliance is not met. When you have multiple checks that need to occur together, you can run all of them with one chain instead of running each check individually. This promotes flexibility and succinct development in your environment.

Check Chains is a feature that is available in Liquibase 4.27.0 and later. It is only available to Liquibase Pro users.

Implement Check Chains

The Check Chains template is essential to implement the Check Chains feature. The template's purpose is to be copied. Once copied, the user customizes the copy to create a chain of quality checks.

Short Name Scope Enabled Severity Customization Description
ChainedChecksTemplate changelog, database

false

Default value: 0

  • 'INFO' | 0
  • 'MINOR' | 1
  • 'MAJOR' | 2
  • 'CRITICAL' | 3
  • 'BLOCKER' | 4

LOGIC CONDITIONAL = null
MESSAGE =

  • The conditions in '<Check Chains shortname>' were met for '<logical conditional>'.
  • The Check Chains include <checknames>.

 This check triggers when the logic conditional evaluates to triggered.

To begin using the Check Chains feature, you must first copy the chained check template.

  1. First run:
    liquibase checks copy --check-name=ChainedChecksTemplate
  2. Then customize your check chain copy by giving it a short name.
  3.  In this example we will call it TableLabelChain
  4. Set the severity of the check chain.
    1. This can be 0, 1, 2, 3, or 4. Learn more here: Use Quality Checks in Automation: Severity and Exit Code
  5. Specify the specific checks to link in this chained check, the logic conditionals, and optional groupings between these checks.
    1. Example 1: If you want two checks to both trigger for TableLableChain to trigger, link them as checkname1 && checkname2.

      2. Tip: If a user types any operator incorrectly, a message appears that states: 

      Invalid value: 'checkname1 & checkname2': The supplied value is not valid. Enter the shortname, logic conditional (using &&, ||, !), and optional (groupings) for your checks. Example: "(shortname1 && shortname2) || shortname3":

      If you see this error message, ensure that your operators are either &&, ||, or !.

    2. Example 2: If you need EITHER two checks to trigger, or one separate check for TableLabelChain to trigger, you would link them as “(checkname1 && checkname2) || checkname3”

      3. Note: Set the logic condition using !, &&, or || operators. The order of operations from highest to lowest precedence is NOT → AND → OR respectively. Grouping with parenthesis allows for enhanced trigger conditions for Check Chains.

  6. In this TableLabelChain example, the goal is for both checks to trigger for TableLabelChain. For this to occur, set TableColumnLimit3 && ChangesetLabelCheck as the logical conditional.

    7. Note: When a check chain is created the linked checks are automatically enabled if they are disabled, and the chain is ready to run. A singular check within the chain can be disabled and when the chain is run, a message will alert the user to this.

    The Check Chains severity setting overrides any individual checks' severity setting. If ChangesetLabelCheck is set to severity 2, but a chained check that includes ChangesetLabelCheck is set to severity 4, then the severity will be set to 4 when the chained check runs.

  7. If you would like to keep the default CLI success message, simply press the Enter key to finish customizing your check chain.
    • The default message is:
      • The conditions in '<Check Chains shortname>' were met for '<logic conditional>'. The Check Chains include <checknames>.
  8. If you would like the CLI success message to be different than the default, set the message you would like to appear when the check chain is successful and then press Enter.
  9. To ensure that the checks are enabled, run liquibase checks show.
  10. If you followed this example, the  TableLabelChain check will be listed among all other checks enabled.
    11. Short Name Scope Enabled Severity Customization Description
    TableLabelChain changelog, database

    false

    Default value: 0

    LOGIC CONDITIONAL = null MESSAGE =

    • The conditions in '<Check Chains shortname>' were met for '<logical conditional>'.
    • The Check Chains include <checknames>.

    		 This check triggers when the logic conditional evaluates to triggered.
  11. To run the chained check:
    liquibase checks run --check-name=TableLabelChain --checks-scope=changelog --changelogfile=<your_changelog_file.xml>
  12. When run successfully, this message appears:
    The conditions in 'TableLabelChain' were met for 'TableColumnLimit3 && 'ChangesetLabelCheck'. The Check Chains include 'TableColumnLimit3::triggered', 'ChangesetLabelCheck::triggered'.

Note: Checks trigger on matched conditions. You want your content to match the checks so you can confirm the Check Chains are triggered.

Troubleshooting

This list covers messages that guide the user back to their desired path while implementing Check Chains in their workflow.

  • If you add a check to a chain that is not enabled and you run the chain, you will receive a message that states:

    This chain is broken! Check '<TableCommentPatternCheck>' is disabled or deleted. Enable check(s) and try again with 'liquibase checks run --checkname='ChainedChecksTemplate1'

    Ensure your checks are enabled to avoid this message.

  • A check within a check chain will not execute separately outside the chain as a standalone check or show on its own in the console output. You can only trigger a check separately that is within a chain by specifying the check in liquibase checks run --check-name=mycheck .

  • Some checks are only applicable to the changelog or the database. It is best practice to separate each check chain by changelog or database checks. Otherwise you will receive a message that states:

      Database checks skipped due to non-applicable object(s) for this check:
      Chained check template (Short names: ExampleCheck) skipped for:
      amount:column,
      uc_name:uniqueConstraint,
      supplier_name:column
      (See 12 more objects by setting command argument --verbose)