Use the Checks Settings Configuration File
The checks settings file includes your configuration of checks, which you can use for a specific project or share across a team or organization. You may have multiple checks settings configuration files and store them in source control or artifact repository for versioning, consistent use, and automation.
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.
By default, the file is called
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.confin the Liquibase working directory, enter Y at runtime.
- To use the in-memory file while running
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-fileparameter. If you do not include the parameter, Liquibase uses the in-memory file or default settings file:
- You can use a custom named check settings file with any
checkscommand. For example, you can use the
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
- If you use Liquibase 4.5.0, you will have the encoded
liquibase.checks-settings.conffile 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.conffile 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.
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.