Configuring Quality Checks

Liquibase provides a default set of checks with default settings defined in the checks settings file.

Quality checks are either static or dynamic. A dynamic check can have multiple configurations, whereas a static check can have one.

  • A check is static if the attributes of the check cannot be customized. You can enable or disable static checks. You cannot copy, customize, or delete static checks.
  • A check is dynamic if there are settings you can customize. Dynamic checks contain values possible to modify according to your needs.
    • You can copy, customize, and reset dynamic checks but cannot delete them.
    • You can copy, customize, delete, and reset the copy of a dynamic check to the parent check’s default settings.
  • All checks can be enabled or disabled. Liquibase Pro users can run unlimited enabled checks, and Liquibase Community users can run the first 5 enabled checks.

For now, Liquibase provides the following static and dynamic checks:

Static checks

Detect GRANT Statements

Attribute Value
Short name SqlGrantWarn
Description

The check warns when generated or raw SQL contains GRANT statements so that you can ensure that the privilege being granted will not lead to security issues.

For example, you have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with at least one changeset that includes the sql, sqlFile, or pro:sqlplus Change Type, and there is a statement that contains GRANT <privilege name>. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with privileges.

Enabled by default Yes

Detect Dropped Tables

Attribute Value
Short name ChangeDropTableWarn
Description

The check warns when a table is being dropped so that you can ensure that dropping the table will not lead to unintentional loss of data. For example, you have one of the following:

  • A formatted SQL changelog file with the DROP TABLE statement
  • A JSON, YAML, or XML changelog file with the dropTable changeset
  • A JSON, YAML, or XML changelog file that includes the sql, sqlFile, or pro:sqlplus Change Type, and there is the statement that contains DROP TABLE

When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with a table being dropped.

Enabled by default Yes

Detect Dropped Columns

Attribute Value
Short name ChangeDropColumnWarn
Description

The check warns when a column is being dropped so that you can ensure that dropping the column will not lead to unintentional loss of data. For example, you have one of the following:

  • A formatted SQL changelog file with the ALTER TABLE TABLE_NAME DROP COLUMN statement
  • A JSON, YAML, or XML changelog file with the dropColumn changeset
  • A JSON, YAML, or XML changelog file that includes the sql, sqlFile, or pro:sqlplus Change Type, and there is the statement that contains ALTER TABLE TABLE_NAME DROP COLUMN

When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with a column being dropped.

Additionally, see the check variations:

  • Statement does not contain the COLUMN keyword: ALTER TABLE TABLE_NAME DROP <column_name>
  • Statement contains a column list: ALTER TABLE TABLE_NAME DROP (<column1_name>,<column2_name>)
Enabled by default Yes

Detect REVOKE Statements

Attribute Value
Short name SqlRevokeWarn
Description

The check warns when generated or raw SQL contains REVOKE statements so that you can ensure that the privilege being revoked will not lead to data access and dependency issues.

For example, you have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with at least one changeset that includes the sql, sqlFile, or pro:sqlplus Change Type, and there is a statement that contains REVOKE <privilege name>. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with privileges.

Enabled by default Yes

Detect Data Type Modification

Attribute Value
Short name ChangeModifyDataTypeWarn
Description

The check warns when a change will result in modification of a data type so that you can ensure that modifying the data type will not lead to unintentional loss of data. For example, you have one of the following:

  • A formatted SQL changelog file with the ALTER TABLE MODIFY COLUMN statement
  • A JSON, YAML, or XML changelog file with a modifyDataType changeset
  • A JSON, YAML, or XML changelog file that includes the sql, sqlFile, or pro:sqlplus Change Type, and there is the statement that contains ALTER TABLE MODIFY COLUMN

When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset that may modify the data.

Additionally, see the check variations:

  • Statement does not contain the COLUMN keyword: ALTER TABLE MODIFY <column_name>
  • Statement contains additional ALTER instead of MODIFY: ALTER TABLE ALTER COLUMN
Enabled by default Yes

Ensure changesets are Labeled

Attribute Value
Short name ChangesetLabelCheck
Description

The check enforces the Liquibase recommendation that labels be assigned to each changeset to provide better deployment control and to enhance traceability of efforts across changesets.

For example, you have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with at least one changeset that does not have labels defined. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with no label.

Additionally, see the following check variation:

  • One label defined on a changeset
  • Multiple labels defined on a changeset
  • No labels defined on a changeset
  • An inherited label from include or include all

Note: Labels are not inherited from the parent changelog, so none of the changesets in an included changelog will automatically get a label. Therefore, the quality checks will warn that the child changesets do not contain a label unless the label has been explicitly added to the child changelog’s changeset.

Enabled by default Yes

Ensure changesets Have a Context Assigned

Attribute Value
Short name ChangesetContextCheck
Description

The check enforces the Liquibase recommendation that contexts be assigned to each changeset to provide better deployment control and to enhance traceability of efforts across changesets.

For example, you have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with at least one changeset that does not have contexts defined. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with no context.

Additionally, see the following check variation:

  • One context defined on a changeset
  • Multiple contexts defined on a changeset
  • No contexts defined on a changeset
  • An inherited context from include or include all
Enabled by default Yes

Ensure changesets Include a Comment

Attribute Value
Short name ChangesetCommentCheck
Description

The check enforces the Liquibase recommendation that comments be added to each changeset to document the purpose of a changeset for other consumers of that changelog.

For example, you have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with at least one changeset that does not have a comment added to it. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with no comment.

Enabled by default Yes

Dynamic checks

Check SQL for a Specific Pattern

Attribute Value
Short name SqlUserDefinedPatternCheck
Description

The check scans generated or raw SQL for the presence of specific patterns so that you can prevent security and velocity issues as early as possible.

Uses

You may have a JSON, YAML, or XML changelog file with one or more changeset that contain raw SQL or produce generated SQL that matches the regular expression. When you execute liquibase checks run against that changelog, Liquibase generates or accesses the SQL generated for the changelog and checks for a match against the defined regular expression. After this, you will receive an alert message about the changeset affected.

You may also have a formatted SQL changelog file to check changesets that have labels, but those labels do not match the check configuration.

To use the SqlUserDefinedPatternCheck check with the specific SQL, you must copy and customize it:

liquibase checks copy --check-name=SqlUserDefinedPatternCheck

Note: See the Configurable attributes table for the attributes you can customize.

Restrictions

You cannot delete or reset the SqlUserDefinedPatternCheck check if it is an original check, not a copy of the check.

You cannot reset a customized copy of the SqlUserDefinedPatternCheck check for the initial value because the check does not have a default value for the SearchString attribute. If you no longer need to run this check, delete or disable it.

Enabled by default No

Configurable attributes for SQL that contains a specific pattern

Name Type Description Validation Default value
SearchString String The substring or regular expression to match with the one in the changelog file SearchString should be a valid string or regular expression. There is no default value
Message String The message you want to print when the check detects a pattern match There is no validation The default value is the following: A match for regular expression <SearchString value> was detected in changeset <changeset id>

Check Table Column Count

Attribute Value
Short name TableColumnLimit
Description

The check ensures that no table has more than a threshold number of columns.

Uses

You may have a formatted SQL changelog file or a JSON, YAML, or XML changelog file with one or more changesets that contain a table with N columns in which N > MAX_COLUMNS. When you execute liquibase checks run against that changelog, you will receive an alert message about the changeset with the exceeded limit.

You can copy and customize the TableColumnLimit check to your specific column limit threshold by running:

liquibase checks copy --check-name=TableColumnLimit

Note: See the Configurable attributes table for the attributes you can customize.

Restrictions

You cannot delete or reset the TableColumnLimit check if it is an original check, not a copy of the check.

You cannot reset a customized copy of the TableColumnLimit check for the initial value. If you no longer need to run this check, delete or disable it.

Enabled by default Yes

Configurable attributes for a table column count limit

Name Type Description Validation Default value
MAX_COLUMNS INT The substring or regular expression to match There is no validation The default value is 50

checks settings file

Another part of the Liquibase quality checks configuration is the checks settings file.

The checks settings file is the file that includes the configuration of checks for a specific project. The file is encoded and should not be manually edited. Use the checks subcommands to copy, customize, enable, or disable rules and update the file.

You can share the checks settings file in your source code control or artifact repository for versioning and consistent use across teams and automation.

Creating the checks settings file

When you start using the checks functionality by running any checks subcommand, Liquibase will create a checks settings file in the Liquibase working directory for you – liquibase.check-settings.conf.

Related links