Getting Started with the checks Command

To build quality, security, and compliance into your database development workflow, start using the Liquibase checks command. You can execute Liquibase checks against a changelog and customize the checks configuration to catch specific scenarios.

Prerequisites

Tip: If you are new to Liquibase, you can follow the Quickstart Guide first.

Ensure you use Liquibase 4.5.0 or later.

Step 1: Running checks against your changelog with the default configuration

The quality checks capability supports all changelog formats. This instruction includes a formatted SQL changelog. If you want to use your own changelog, example output may differ.

  1. Create a new changelog.sql file and add the following:
  2. --liquibase formatted sql
    				
    --changeset your.name:1 labels:v0 context:all
    create table person (
    	id int primary key,
    	name varchar(50) not null,
    	address1 varchar(50),
    	address2 varchar(50),
    	city varchar(30)
    )
    				
    --changeset your.name:2 labels:v0 context:all
    create table company (
    	id int primary key,
    	name varchar(50) not null,
    	address1 varchar(50),
    	address2 varchar(50),
    	city varchar(30)
    )
    				
    --changeset other.dev:3 labels:v0 context:all
    alter table person add column country varchar(2)
    
    --changeset other.dev:4 labels:v0 context:all
    drop table person;
  3. Open your CLI and navigate to the directory with the changelog file you will use. Start by executing checks against the sample changelog file using the default configuration provided by Liquibase:
  4. liquibase checks run

    Note: You will be prompted to create a new configuration file for checks if one does not already exist.

If you use the sample changelog provided in the instruction, you may notice that the last changeset in changelog.sql contains a drop table statement, which is flagged by one of the checks in the default configuration.

Executing Quality Checks against changelog.sql
No valid Liquibase Pro license key detected!
Unlock unlimited checks with a free Pro license Key from https://liquibase.com/protrial
Execution limited to 5 checks.
Checks completed validation of the changelog and found the following issues:
Changeset ID:       4
Changeset Filepath: changelog.sql
Check Name:         Warn when 'DROP TABLE' detected (ChangeDropTableWarn)
Message:            Liquibase recommends that changesets which result in tables
					being dropped are reviewed carefully to prevent the
					unintentional loss of data.  Review this changeset to
					confirm that the referenced table is being dropped safely.

Changesets Validated:
  ID: 1; Author: your.name; File path: changelog.sql
  ID: 2; Author: your.name; File path: changelog.sql
  ID: 3; Author: other.dev; File path: changelog.sql
  ID: 4; Author: other.dev; File path: changelog.sql

Checks run against each changeset:
  Warn on Detection of 'GRANT' Statements
  Warn on Detection of 'REVOKE' Statements
  Warn when 'DROP TABLE' detected
  Warn when 'DROP COLUMN' detected
  Warn when 'MODIFY <column>' detected

Checks Skipped Due to Community Limit of 5 Checks:
  Check Table Column Count
  Changesets Must Have a Label Assigned
  Changesets Must Have a Context Assigned
  Changesets Must Have a Comment Assigned
				
Liquibase command 'checks run' was executed successfully.

Step 2: Disabling checks in the default configuration

You can disable any checks by using the checks disable command.

To disable a check, you need to know the short name, which you can get by running the checks show command. The show subcommand lists information and customization settings for available checks including the check’s full name, short name, description, enabled status, and customization options. The short name for the DROP TABLE check is ChangeDropTableWarn.

Then, run the name in the --check-name parameter with the disable subcommand:

liquibase checks disable --check-name=ChangeDropTableWarn

Note: Liquibase will save the configuration change to your checks configuration file (the default file is liquibase.checks-settings.conf) and print the configuration again to show the change.

If you execute the checks run command one more time, no issues will be detected.

Executing Quality Checks against changelog.sql
No valid Liquibase Pro license key detected!
Unlock unlimited checks with a free Pro license Key from https://liquibase.com/protrial
Execution limited to 5 checks.

Changesets Validated:
  ID: 1; Author: your.name; File path: changelog.sql
  ID: 2; Author: your.name; File path: changelog.sql
  ID: 3; Author: other.dev; File path: changelog.sql
  ID: 4; Author: other.dev; File path: changelog.sql

Checks run against each changeset:
  Warn on Detection of 'GRANT' Statements
  Warn on Detection of 'REVOKE' Statements
  Warn when 'DROP COLUMN' detected
  Warn when 'MODIFY <column>' detected
  Check Table Column Count
  Checks Skipped Due to Community Limit of 5 Checks:
  Changesets Must Have a Label Assigned
  Changesets Must Have a Context Assigned
  Changesets Must Have a Comment Assigned
				
Liquibase command 'checks run' was executed successfully.

Note: To enable a check, use the checks enable command.

Step 3: Creating and using a custom check

Some checks have customization options that allow you to adjust the parameters used to determine whether a changeset meets the criteria of the check. You can adjust these parameters using the checks copy command or checks customize command.

  1. Create a check that finds table truncation statements in a sample changelog by generating a copy of the SqlUserDefinedPatternCheck check:
  2. liquibase checks copy --check-name=SqlUserDefinedPatternCheck
  1. Provide a short name, search string, and message for your check:
  2. Give your check a short name for easier identification (alpha-numeric characters only) (default "SqlUserDefinedPatternCheck1"):
    SqlTruncateCheck
    New check 'SqlTruncateCheck' created from 'SqlUserDefinedPatternCheck'
    
    Set 'SEARCH_STRING' (current: 'null'):
    (?i)^(\s*)(TRUNCATE)
    Set 'MESSAGE' (current: 'A match for regular expression <SEARCH_STRING> was detected in Changeset <CHANGESET>.') (default "A match for regular expression <SEARCH_STRING> was detected in Changeset <CHANGESET>."):
    Table truncation detected.  Review this changeset to ensure data is not unintentionally deleted.
    Customization complete. Review the table below to confirm your changes.

    Once you have completed the form, the checks configuration is printed for your review.

  1. Add the following to the changelog.sql file and save your changes:
  2. --changeset other.dev:4 labels:v0 context:all
    truncate person;
  1. Execute the checks run subcommand again:
  2. liquibase checks run

    The new check indicates that there is an issue with your new changeset:

    Checks completed validation of the changelog and found the following issues:
    Changeset ID:       5
    Changeset Filepath: changelog.sql
    Check Name:         Check for specific patterns in sql (SqlUserDefinedPatternCheck)
    Message:            Table truncation detected.  Review this changeset to ensure
                        data is not unintentionally deleted.

The following pages will help you proceed with all quality checks capabilities: