pkNames

pkNames is a custom policy check that ensures all primary key names have the pattern tablename_pkey.

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

This example works for relational databases. 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.

1

Add this code to your Checks Settings file:

pkNames Quotes Python Script
# # #
# # # This script ensures all primary key names have the pattern PK_tablename
# # #
# # # Notes:
    # # #

# # #
# # # Helpers come from 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()

# # #
# # # Retrieve database object
# # #
database_object = liquibase_utilities.get_database_object()

# # #
# # # Skip
if not a table
# # #
if liquibase_utilities.is_table(database_object):
    table_name = database_object.getName()
pk_object = database_object.getPrimaryKey()
# # #
# # # Skip
if table doesn 't have PK
# # #
if pk_object is None:
    liquibase_logger.info(f "Table \"{table_name}\" does not have a primary key. Check skipped.")
else:
    pk_name_current = pk_object.getName()
pk_name_standard = f "PK_{table_name}"
if pk_name_standard not in pk_name_current:
    liquibase_status.fired = True
status_message = str(liquibase_utilities.get_script_message()).replace("__CURRENT_NAME__", f "\"{pk_name_current}\"")
status_message = status_message.replace("__NAME_STANDARD__", f "\"{pk_name_standard}\"")
liquibase_status.message = status_message
sys.exit(1)

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

Provide a short name for the Policy check

A short name is a descriptive name that indicates what you want the check to search for in the database or changelog. In this example, we will provide SqlTruncateCheck as the short name, because we will be searching for any instances of Truncate. The CLI will indicate that the new check was created from SqlUserDefinedPattern check successfully:

New check 'SqlTruncateCheck' created from 'SqlUserDefinedPatternCheck'

3

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

In this example we will name the check: pkNames

4

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

5

Set SCRIPT_DESCRIPTION.

In this example, we will set the description to:

This script checks to see if all primary key names have the pattern PK_tablename.

6

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.

7

Set the SCRIPT_MESSAGE.

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

Primary key name __CURRENT_NAME__ must include table name. Please use (__NAME_STANDARD__) instead.
8

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/pk-names.py.

9

This check does not require a SCRIPT_ARGUMENT, so leave this blank.

10

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.

pkNames - Liquibase