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 may have multiple checks settings files and store them in source control or artifact repository for versioning, consistent use, and automation. By default, the file is called liquibase.checks-settings.conf.

In Liquibase 4.5.0, the checks settings file is encoded, while Liquibase 4.6.0 and later versions provide unencoded checks settings files. An unencoded file is easier to inspect and resolve merge conflicts with source control.

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.

Creating the checks settings file

When you start using the quality checks functionality by running any checks command, Liquibase identifies the need for a checks settings file:

  • To create the default checks settings file named liquibase.checks-settings.conf in the Liquibase working directory, enter Y at runtime.
  • To use the in-memory file while running run or show, enter N at runtime. Other subcommands require a checks settings file to save the changes for checks.
  • To use a checks settings file customized for a specific environment or project, pass it with the --checks-settings-file parameter. If you do not include the parameter, Liquibase uses the in-memory file or default settings file: liquibase.checks-settings.conf.
  • You can use a custom named check settings file with any checks command. For example, you can use the --checks-settings-file command argument:
    liquibase checks show --checks-settings-file=<my-custom-checks.conf>

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.

Automatic update of checks settings file 4.5.0 with Liquibase 4.6.0+

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