varchar2MustUseChar

varchar2MustUseChar is a custom policy check that ensures a varchar 2 column states char. The default is bytes, but char is required.

Learn how to create and customize the varchar2MustUseChar Liquibase Custom Policy Check using a Python script.

This example works for Oracle. You can use this check as it is or customize it further to fit your needs in your SQL database.

For a conceptual overview of this feature, see Liquibase Pro Custom Policy Checks.

Before you begin

*Last updated: July 21, 2025*

Scope	Database
database	Oracle

Liquibase Pro 4.29.0+
Configure a valid Liquibase Pro license key
Python 3.10.14+. See here for the official Python tutorial
Create a Check Settings file
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+.

Procedure

These steps describe how to create the Custom Policy Check. It does not exist by default in Liquibase Pro.

Add this code to your Checks Settings file:

varchar2MustUseChar Python Script

# # # Copyright 2024 Liquibase, Inc.
# # # This script ensures a varchar2 column states char
# # #
default is bytes but we prefer char
# # # Limitations:
    # # #

# # #
# # # Script helper comes from Liquibase
# # #
import liquibase_utilities
import sys
import liquibase_changesets

# # #
# # # main
# # #

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

# # #
# # # Retrieve status handler
# # #
liquibase_status = liquibase_utilities.get_status()

# # #
# # # Retrieve all changes in changeset
# # #
changes = liquibase_utilities.get_changeset().getChanges()

# # #
# # # Loop through all changes
# # #
for change in changes:
    # # #
# # # LoadData change types are not currently supported
# # #
if "loaddatachange" in change.getClass().getSimpleName().lower():
    liquibase_logger.info("LoadData change type not supported. Statement skipped.")
continue
# # #
# # # Retrieve sql as string, remove extra whitespace, split into statements
# # #
raw_sql = liquibase_utilities.strip_comments(liquibase_utilities.generate_sql(change)).casefold()
raw_sql = " ".join(raw_sql.split())
raw_statements = liquibase_utilities.split_statements(raw_sql)
# print(f "Raw statements: {raw_statements}")
# # #
# # # Process each statement
# # #
for raw_statement in raw_statements:
    sql_list = raw_statement.split()
# # #
# # # CREATE[SCHEMA.] TABLE NAME(column1 datatype1, column2 datatype2, ...)
# # #
try:
if sql_list[0] == "create"
and sql_list[1] == "table":
    # # #
# # # Remove schema and parenthesis
if provided
# # #
table_name = sql_list[2].split(".")[-1]
start = table_name.rfind("(")
if start != -1:
    table_name = table_name[0: start]
else:
    raise UserWarning
except IndexError:
    liquibase_logger.warning(f "Unsupported Create Table statement skipped: {raw_statement}")
continue
except UserWarning:
    liquibase_logger.info(f "Non Create Index statement skipped: {raw_statement}")
continue
# # #
# # # Process column list
# # #
column_list = []
search_string = f "{table_name} ("
start = raw_statement.find(search_string)
if start == -1:
    liquibase_logger.warning(f "Unsupported Create Table statement skipped: {raw_statement}")
continue
start += len(search_string)
end = raw_statement.rfind(")")
if end != -1:
    column_list = [column_info.strip() for column_info in raw_statement[start: end].split(",")]
# # #
# # # Look
for varchar2 in column list
# # #
data_type_size = len("varchar2")
data_type = "varchar2"
for name_type in column_list:
    column_info = name_type.split(" ", 1)
if len(column_info) < 2 or column_info[0] == "constraint":
    continue
column_name = column_info[0]
column_type = column_info[1]
# print(f "Name type: {column_name}")
# print(f "Column_type: {column_type}")
if column_type[0: data_type_size] == data_type and not column_type.endswith("char)"):
    liquibase_status.fired = True
status_message = str(liquibase_utilities.get_script_message()).replace("__COLUMN_NAME__", f "\"{column_name}\"")
liquibase_status.message = status_message
sys.exit(1)

# # #
# # # Default
return code
# # #
False

Initiate the customization process

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.

Give your check a short name so you can easily identify what Python script it is associated with

Use up to 64 alpha-numeric characters only.

In this example, we will name the check:

varchar2MustUseChar

Set the Severity to return a code of 0-4 when triggered.

These severity codes allow you to determine if the job moves forward or stops when this check triggers. Learn more here: Use Policy Checks in Automation: Severity and Exit Code options: 'INFO'=0, 'MINOR'=1, 'MAJOR'=2, 'CRITICAL'=3, 'BLOCKER'=4

Set the SCRIPT_DESCRIPTION

In this example, we will set the description to:

This script ensures that all columns define Char instead of Bytes.

Set the SCRIPT_SCOPE

In this example, we will set the scope to:

database: 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.

Set the SCRIPT_MESSAGE

This message will display when the check is triggered. In this example we will use:

This script identified that some columns use Bytes instead of Char. It is recommended this be fixed before proceeding.

Set the SCRIPT_PATH

This is the relative path where your script is stored in relation to the changelog specified in --changelog-file, whether it is stored locally or in a repository.

In this example, we will set the path to:

scripts/varchar-max-size.py.

Set the SCRIPT_PATH

This is the relative path where your script is stored in relation to the changelog specified in --changelog-file, whether it is stored locally or in a repository.

In this example, we will set the path to:

scripts/varchar2-must-use-char.py.

Set the SCRIPT_ARGUMENT

This allows you to pass dynamic information into the Custom Policy Check without modifying the Python code. This is important so you do not hard code values into your check that may change over time or if you have different teams with different thresholds. For example, if you specify MAX_SIZE=10 in 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.

Set the REQUIRES_SNAPSHOT

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.