Write Dynamic Status Messages for Custom Policy Checks

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.

Prerequisites

  1. Ensure you meet the prerequisites specified on Create a Custom Policy Check.
  2. Follow the steps in that tutorial until the step for "Set the script message."

Step-by-step guide

  1. In the CLI, at the Set SCRIPT_MESSAGE prompt, specify a message to display when the check triggers. Specify one or more variables to display dynamic content in the message. For example:
    2. Column __COLUMN_NAME__ does not conform to your policies!
  2. 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:
      • 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.

  3. (Optional) If you defined multiple dynamic variables in Steps 1 and 2, subsequently use replace() again for each one:
    4. status_message = status_message.replace("__TABLE_NAME__", f"\"{table_name}\"")
  4. Send your dynamic status message to the Liquibase API:
    5. liquibase_status.message = status_message

Sample 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.

Next steps

Now that you've specified your dynamic status message, continue following the steps to Create a Custom Policy Check.