Use the Checks Settings Configuration File

The checks settings file lets you customize your quality checks for a specific project or to share a configuration across a team or organization. You can have multiple checks settings files and store them in source control or artifact repository for versioning, consistent use, and automation.

In Liquibase 4.25.0 and later, you can group together multiple checks settings files with a checks package. For more information, see Quality Checks Packages.

The checks settings file can have the .conf or .yaml extension. By default, the file is called liquibase.checks-settings.conf.

Create a checks settings file

To create a checks settings file for the first time:

  1. Run any quality check command:

    liquibase checks show

    Enter 1 to use the default checks settings file (liquibase.checks-settings.conf). When successful, Liquibase displays a list of checks enabled by default plus the following message:

    liquibase.checks-settings.conf successfully created!

    2. Alternatively, enter 2 to specify a custom name for your settings file.

    Either way, Liquibase enables some useful quality checks for you by default. You can modify which checks are active in your settings file by using some of the commands described in the next step.

  2. If you want to create and customize an additional checks settings file after creating your initial file (liquibase.checks-settings.conf):
    1. Use the shell cp command (or copy on Windows) to create a duplicate settings file with a custom name, in this case oracle-checks.yaml.
      2. cp liquibase.checks-settings.conf oracle-checks.yaml
    2. Use checks bulk-set to disable all checks within the custom settings file you just created.
      3. liquibase checks bulk-set --disable
    3. Use checks enable to enable only the checks you want to include (see a list of checks to choose from):
      4. liquibase checks enable --check-name=<checkName1>
      liquibase checks enable --check-name=<checkName2>
    4. Use checks show to verify that you've enabled all the checks you want:
      5. liquibase checks show

You can further modify an existing checks settings file at any time. For more information, see Quality Checks Commands.

Use the checks settings file

You can run the quality checks that are enabled in your settings file by using the checks run command:

liquibase checks run --checks-settings-file=my_file_name.yaml

Here are some tips to use your settings file:

  • To use the in-memory file while running run or show, enter N at runtime. Other commands require a checks settings file to save the changes for checks.
  • To use a checks settings file customized for a specific environment or project, specify the name with the --checks-settings-file parameter. If you do not specify this parameter, Liquibase uses the in-memory file or default settings file: liquibase.checks-settings.conf.
  • To group multiple checks settings files together and run them in a single run or show command, create a checks package.

Warning: Do not manually modify the checks settings file because it may cause unrecoverable and unsupported errors. You should only modify the file with Liquibase commands.

Encoding changes between Liquibase 4.5.0 and 4.6.0

The checks settings file is encoded in Liquibase 4.5.0 and unencoded in Liquibase 4.6.0+. An unencoded file is easier to inspect and resolve merge conflicts with source control.

When you use an encoded checks settings file from Liquibase 4.5.0 with Liquibase 4.6.0 or later versions, Liquibase will automatically back up your checks settings file as liquibase.checks-settings.conf.v4.5 and update it.

In most cases, you do not need to take any action. However, when you work in an environment in which a Liquibase 4.5.0 user cannot upgrade to version 4.6.0 and must use the same shared checks settings file, the Liquibase 4.5.0 user must specify the compliant checks settings file 4.5.0 by using --checks-settings-file=<mybackedupfile.conf.v4.5>.

  • If you use Liquibase 4.5.0, you will have the encoded liquibase.checks-settings.conf file and it will remain encoded so long as you use version 4.5.0.
  • If you have Liquibase 4.6.0 or later versions when you start using quality checks, your first liquibase.checks-settings.conf file will be unencoded by default.
  • If you have Liquibase 4.6.0 or later versions and use an encoded checks settings file 4.5.0, it will be backed up and unencoded automatically.

File format

The liquibase.checks-settings.conf internal file format has changed over time to simplify the process of managing the file in source control.

  • In Liquibase 4.5.0, the file was encoded, which made it difficult to merge changes.
  • In Liquibase 4.6.0 through Liquibase 4.23.0, this was remedied by changing the file to an unencoded proprietary format.
  • In Liquibase 4.23.1 and later, the file format was changed to YAML for better readability and easier management. It is still a best practice to use Liquibase commands to manage this file and never make manual edits.

    • Note: The Liquibase 4.23.1+ file format is unreadable by 4.23.0 and earlier. If multiple users or pipelines share a checks settings file, you must install Liquibase 4.23.1+ for all users and pipelines that call on the file.

Related links