Write Dynamic Status Messages for Custom policy checks

Last updated: July 14, 2025

Liquibase displays the status message after you run a custom policy check. Normally, this is just a static string you define in the CLI. However, you can use your Python script to specify dynamic content to display in your status message.

This guide shows where to configure dynamic variables in your Python script and how Liquibase can expand those variables into useful values.

Before you begin

  • Create a Custom Policy Check.

  • You'll need the short name for your check. If you have forgotten, you can look through all of your checks using liquibase checks show --check-status=ALL.

Procedure

1

Initiate the customization process.

Run this command in the CLI.

Be sure to replace your_check_name with the short name you set for your check.

liquibase checks customize --check-name=your_check_name
2

Set a SCRIPT_MESSAGE.

When you run the command to customize your policy check, several options will appear, such as SEVERITY, SCRIPT_DESCRIPTION, and SCRIPT_SCOPE. You can edit any of these to update your existing policy check, or simply press Enter to keep the current value you set when creating the check.

When you reach the option for SCRIPT_MESSAGE, specify a message to display when the check is triggered. Specify one or more variables to display dynamic content in the message. For example:

Column __COLUMN_NAME__ does not conform to your policies!

Once your SCRIPT_MESSAGE is set, continue pressing Enter to submit and save your changes.

3

In your Python script, use Liquibase Python Modules to define variables for your message.

In your Python script, use Liquibase Python Modules to define variables for your message.

  • Dynamic phrase (one or more): the phrase you want to dynamically insert into your message. For example, the name of the column.

column_name = liquibase_utilities.get_database_object().getName()

Note: This technically returns the name of the database object, which might not be a column. We'll handle this case later!

  • Status message: gets the message you specified in the CLI. Then append the Python replace() function to do the replacement.

If you defined multiple dynamic variables, subsequently use replace() again for each one.

status_message = str(liquibase_utilities.get_script_message()).replace("__COLUMN_NAME__", f"'{column_name}'")

Note: In this case, we use Python formatted string notation (f-strings) because we're using a variable inside it.

4

Send your dynamic status message to the Liquibase API.

liquibase_status.message = status_message
Example script
# This script ensures all VARCHAR columns are under a maximum size

# Modules come from Python and Liquibase
import sys
import liquibase_utilities

# Retrieve log handler
# Ex.liquibase_logger.info(message)
liquibase_logger = liquibase_utilities.get_logger()

# Retrieve status handler
liquibase_status = liquibase_utilities.get_status()

# Retrive maximum size from check definition
max_size = int(liquibase_utilities.get_arg("VARCHAR_MAX"))

# Retrieve database object
database_object = liquibase_utilities.get_database_object()

# Skip
if not a varchar column
if "column" in database_object.getObjectTypeName().lower() and "varchar" in str(database_object.getType()).lower():
    column_name = database_object.getName()
column_size = int(database_object.getType().getColumnSize())

if column_size > max_size:
    liquibase_status.fired = True
status_message = str(liquibase_utilities.get_script_message()).replace("__COLUMN_NAME__", f "'{column_name}'")
status_message = status_message.replace("__COLUMN_SIZE__", f "{max_size}")
liquibase_status.message = status_message
sys.exit(1)

# Default
return code
False

For more sample scripts, see GitHub: liquibase/custom_policychecks.

Write Dynamic Status Messages for Custom policy checks - Liquibase