Create a Custom policy check

This tutorial shows you how to create, customize, and run a Liquibase custom policy check using a sample Python script. For a conceptual overview of this feature, see Liquibase Pro Custom Policy Checks.

For examples of more advanced Python scripts and guidance on writing Python code to use in the Liquibase policy checks framework, see Sample Custom Policy Check Scripts.

Before you begin

*Last updated: July 21, 2025*

  • Liquibase Pro 4.29.0+

  • Python 3.10.14+. See here for the official Python tutorial

  • Java Development Kit 17+ (available for Open JDK and Oracle JDK)

  • Linux, macOS, or Windows operating system

  • Ensure the Liquibase Checks extension is installed.

    • In Liquibase 4.31.0+, it is already installed in the /liquibase/internal/lib directory, so no action is needed.

    • If the checks JAR is not installed, download liquibase-checks-<version>.jar and put it in the liquibase/lib directory.

    • Or, if you use Maven, add this dependency to your pom.xml file: <dependency> <groupId>org.liquibase.ext</groupId> <artifactId>liquibase-checks</artifactId> <version>2.0.0</version> </dependency>

Tip: Downloading Python itself is not required to create custom checks in the Liquibase checks framework, but it may be useful to test checks against Python 3.10.14+.

Create a Custom policy check

1

Create a new file in your Liquibase working directory or a subdirectory like /scripts.

This file will contain the Python script that is your custom policy check. In this example, we title our new file custom_check_no_tables.py.

2

Open the new custom_check_no_tables.py file and add the following custom policy check to it

    # import Liquibase modules containing useful functions
    import liquibase_utilities as lb
    import sys

    # define reusable variables
    obj = lb.get_database_object()  # database object to examine
    liquibase_status = lb.get_status()  # Status object of the check

    # write check logic
    # this condition checks if the current object is a table
    # and whether it starts with the prefix 'tbl_'
    if lb.is_table(obj) and not obj.getName().lower().startswith("tbl_"):
    # indicate that the custom check has been triggered
    liquibase_status.fired = True
    # set the message for Liquibase to return when check is triggered
    liquibase_status.message = "Tables must start with the prefix tbl_. Add this prefix."
    # halt execution of the script
    sys.exit(1)

    # default return code
    False

Note: Liquibase will run the check against every object in the database, so this script doesn't need a Python looping mechanism to iterate through database objects.