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 Policy 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.

Create a Check Chain

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 chain checks together with conditional logic, you must clone and modify the ChainedChecksTemplate check:

1. Copy the chained check template:

   liquibase checks copy --check-name=ChainedChecksTemplate

2. Then customize your check chain copy by giving it a short name. In this example we will call it TableLabelChain
3. Set the severity of the check chain. Enter 0, 1, 2, 3, or 4.
4. 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. 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”

   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.

5. 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.

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.


6. 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>.

7. 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.
8. To ensure that the checks are enabled, run liquibase checks show.
9. If you followed this example, the  TableLabelChain check will be listed among all other checks enabled.

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.

Use Your Check Chain

1. To run the chained check:
   

   liquibase checks run --check-name=TableLabelChain --checks-scope=changelog --changelogfile=<your_changelog_file.xml>

2. 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

Disabled or deleted check

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.

Check execution

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.

Check scope

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)

Syntax errors

If you types any operator incorrectly while setting the logic of your check chain, Liquibase displays the following error message:

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 !.