Configure a Custom policy check

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.

In this example, we will name the checkCustomCheckNoTables.

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

In this example, we will set the severity to 1

• 'INFO' | 0

• 'MINOR' | 1

• 'MAJOR' | 2

• 'CRITICAL' | 3

• 'BLOCKER' | 4

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.

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.

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

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.

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 calledproject/, and your script is inproject/scripts/, the relative path to the script would bescripts/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.

This allows you to pass dynamic information into the custom policy check without modifying the Python code. For example, if you specifyMAX_SIZE=10in 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.

• Optional:

  In Liquibase Secure 4.31+, Custom policy checks users can implement Custom Policy Check property substitution when they are setting theSCRIPT_ARGSduring check creation. You can reference properties such as environment variables, CLI arguments, or values from the defaults file using standard property substitution syntax. Learn how to use this functionality here:

  Apply Property substitution in Custom policy checks

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.