What are some examples of Custom policy check scripts?

Guidance on writing Python code

Warning: Custom policy checks are not isolated and can interact both with local file systems and network utilities like the targeted database. It is a best practice to review all checks prior to execution to ensure they only affect the intended object(s).

Liquibase modules

When you download the Liquibase Checks extension, you also get a built-in set of Liquibase modules that you can use to easily call the Liquibase API. For example, there are modules containing functions to:

• Find the ID of a changeset

• Get a list of columns in a table

• Check if a database object is a table, column, index, foreign key, or other object

• Modify internal Python script bindings

For a list of Liquibase modules and functions you can call on, see Liquibase Python Modules.

Python libraries

If you're new to Python, read the official Python tutorial before writing any scripts. See the Python Standard Library for information on built-in functions. You can always import these at the beginning of your script.

Liquibase comes pre-installed with a GraalPy virtual environment. In addition to the built-in Liquibase modules, this virtual environment contains the following Python modules that aren't part of the Python Standard Library:

• simplejson

• sqlparse

• urllib3

However, you cannot install additional modules in the built-in virtual environment because it is packaged in the Liquibase checks extension JAR file. To install additional modules, you must create your own virtual environment and install them yourself, including a package containing the Liquibase API. For more information, see Create a Python Virtual Environment.

Looping behavior

When you execute the checks run command, Liquibase always runs every enabled policy check against every object the check targets. This works the same for Custom Policy Checks. For example, Liquibase runs any custom policy check with a --checks-scope setting of:

• changelog: once per changeset in that changelog. If the changelog uses include or includeAll to reference child changelogs, the script also runs once per changeset in each of those child changelogs.

• database: once per database object. Liquibase generates a database snapshot once and then runs your script against every object in the snapshot. Liquibase runs your check against the schema(s) you specify.

Note: If you write a custom policy check that is individually performance-heavy, and you have a very large changelog or database, Liquibase may take a long time to run your custom check against all objects.

Script status

Your Python script doesn't need to return a value. Liquibase uses an object called Status to track the state of your check:

• Whether the check has triggered (fired)

• The message to display as output

At the point in your script where the check should trigger, use the liquibase_utilities module to modify the Status object:

import liquibase_utilities as lb liquibase_status = lb.get_status() if [trigger condition]: liquibase_status.fired = True liquibase_status.message = lb.get_script_message() sys.exit(1) False

Notes on the preceding code sample:

• liquibase_utilities.get_status().fired is set to False by default. You must set it to True or else the Liquibase policy checks framework assumes the check didn't trigger.

• liquibase_utilities.get_script_message() returns the static string you specify when you create your Liquibase custom policy check object in the CLI. If you left SCRIPT_MESSAGE blank while configuring your check in the CLI, get_script_message() returns an empty string. If you want to add a message later, you have to checks customize your check or specify your message directly in your Python script as a string. If you want to insert dynamic content into this string, such as the name of a database object, see Write Dynamic Status Messages for Custom Policy Checks.

• Normally, sys.exit(1) signifies a program failure. However, in this case, you just want to use it to force Python to exit. In this case, Liquibase is working just how you want it to! You can specify a more meaningful exit code by configuring the severity level of your custom check in the CLI. See Create a Custom Policy Check.

• Specify False at the end of your script to follow Python convention. This code is evaluated if the check doesn't trigger, but has no effect.