Configure a Custom policy check

Procedure

Configure your custom policy check in the CLI.

1

Initiate the customization process

In the CLI, run this command:

liquibase checks customize --check-name=CustomCheckTemplate

The CLI prompts you to finish configuring your file. A message displays:

This check cannot be customized directly because one or more fields does not have a default value.

Liquibase will then create a copy of CustomCheckTemplate and initiate the customization workflow.

2

Give your new check a short name for easier identification

In this example, we will name the check CustomCheckNoTables.

Tip: For ease of use, it is a best practice to name your custom check after your Python script.

3

Set the severity to return a code of 0–4 when triggered.

In this example, we will set the severity to 1

  • 'INFO' | 0

  • 'MINOR' | 1

  • 'MAJOR' | 2

  • 'CRITICAL' | 3

  • 'BLOCKER' | 4

4

Set the SCRIPT_DESCRIPTION

In this example, we will set the description to:

This script looks to see if any tables exist and notifies you if one is detected.

5

Set the SCRIPT_SCOPE

In this example, we will set the scope to database. The Python sample provided in this tutorial requires it.

In general, you should set the scope to changelog or database depending on what your custom script does:

  • changelog

    : for example, if your check looks for syntax patterns or attributes in your Liquibase Changelog (the changes you author in your repository). With this value, the check runs once per changeset.

  • database

    : for example, if your check looks for the presence of keys, indexes, or table name patterns in your database schema (including Liquibase Tracking Tables). With this value, the check runs once for each database object.

Tip: It is a best practice for custom checks to have only one scope, not both.

6

Set SCRIPT_MESSAGE

This message will display when the check is triggered. In this example we will leave this blank, as we are handling the message in the script.

7

Set SCRIPT_PATH to the location of your script

You can provide either:

  • a relative path, which is based on the location of the changelog file you specify with --changelog-file. This means that the path is relative to where that changelog file is stored.

    Example:

    If your changelog is in a folder called project/, and your script is in project/scripts/, the relative path to the script would be scripts/your-script.py.

    OR

  • An absolute path, which starts from the root of the your computer's file system and includes the full path to the script. Example: The full path to the script would be:

    /Users/yourname/project/scripts/your-script.py

In this example, we will set the path to: scripts/custom_check_no_tables.py.

8

Set the SCRIPT_ARG

This allows you to pass dynamic information into the custom policy check without modifying the Python code. For example, if you specify MAX_SIZE=10 in the CLI, you can retrieve it in your code with a variable: max_size = int(liquibase_utilities.get_arg("MAX_SIZE")). If you customize your check later, you can specify a new value in the CLI. If you don't need dynamic arguments, leave this field blank.

9

Set REQUIRES_SNAPSHOT

If your script scope is changelog, set whether the check requires a database snapshot. Specify true if your check needs to inspect database objects. (If your script scope is database, Liquibase always takes a snapshot, so this prompt does not appear.)

Note: The larger your database, the more performance impact a snapshot causes. If you cannot run a snapshot due to memory limitations, see Memory Limits of Inspecting Large Schemas.