Liquibase Python Modules

Liquibase provides an API you can call on in your Python Custom Policy Checks. The Liquibase Checks extension comes with several modules you can import in your scripts to access this API:

liquibase_changesets
liquibase_constants
liquibase_database
liquibase_json
liquibase_utilities

This documentation page lists the callable methods and functions contained in these modules. You can use these to access necessary information about your changelog and database to run your custom policy checks.

For real-world Python scripts that access these modules, see Sample Custom Policy Check Scripts.

Python modules

The Python Standard Library is included when you download Python. Liquibase also natively supports the following Python modules:

You can use these modules for additional functionality in your custom policy checks, such as parsing complex SQL queries.

The built-in Liquibase virtual environment cannot support additional modules. If you want to use more, you must create your own virtual environment and configure Liquibase to run scripts using your custom executable instead.

In your custom virtual environment, you can install the Liquibase Python modules and natively supported Python modules in a package called liquibase-checks-python. For more information, see Create a Python Virtual Environment.

Import syntax

By default, you can import Liquibase modules using the following syntax:

import <module name>

If you use a custom virtual environment instead of the built-in virtual environment Liquibase provides, you must use the following syntax instead:

from liquibase-checks-python import <module name>

`liquibase_changesets`

These functions are available to you after importing liquibase_changesets.

Functions to pull information from the given changeset path. The changeset is always the input parameter for these attributes.

Function	Return
`get_author(changeset)`	Provides the changeset author
`get_contexts(changeset)`	Provides the changeset contexts
`get_file_path(changeset)`	Provides the changeset file path
`get_id(changeset)`	Provides the changeset ID
`get_labels(changeset)`	Provides the changeset labels
`is_always_run(changeset)`	Provides the value of `runAlways` for this changeset
`is_run_on_change(changeset)`	Provides the value of `runOnChange` for this changeset

`liquibase_database`

These functions are available to you after importing liquibase_database.

Methods to access, or return, database attributes. The database is always the input parameter for these attributes.

Function	Return
`get_database_product_name(database)`	Provides the database product name
`get_database_product_version(database)`	Provides the database product version
`get_default_schema_name(database)`	Provides the default schema for this database
`get_short_name(database)`	Provides the database short name

`liquibase_json`

These functions are available to you after importing liquibase_json.

Functions to access, or return, JSON attributes. These are functions to parse a JSON snapshot of your database and access, or return, dictionary objects.

Function	Input Parameter	Return
`get_column(snapshot, table_name, column_name)`	`snapshot`: the snapshot to parse `table_name`: the name of the table to search for `column_name`: the name of the column to search for	Provides the specified Column Dict object for a table
`get_column_size(column)`	`column`: the Column Dict object	Provides the specified Column's size
`get_column_type_name(column)`	`column`: the Column Dict object	Provides the specified Column's type name
`get_columns(snapshot, table_name)`	`snapshot`: the snapshot to parse `table_name`: the name of the table to search for	Provides a list of Column Dict objects for a table such as a JSON serialized representation of the Liquibase internal `DatabaseObject` class. Example output: `{'column': {'name': 'name', 'nullable': True, 'order': '1!{java.lang.Integer}', 'relation': 'liquibase.structure.core.Table#0eab104', 'snapshotId': '0eab105', 'type': {'characterOctetLength': '20!{java.lang.Integer}', 'columnSize': '20!{java.lang.Integer}', 'columnSizeUnit': 'BYTE!{liquibase.structure.core.DataType$ColumnSizeUnit}', 'dataTypeId': '1!{java.lang.Integer}', 'radix': '10!{java.lang.Integer}', 'typeName': 'bpchar'}}}`
`get_indexes(snapshot, table_name)`	`snapshot`: the snapshot to parse `table_name`: the name of the table to search for	Provides a List of Index Dict objects for a table
`get_primary_key(snapshot, table_name)`	`snapshot`: the snapshot to parse `table_name`: the name of the table to search for	Provides a Primary Key Dict object for a table
`get_table(snapshot, table_name)`	`snapshot`: the snapshot to parse `table_name`: the name of the table to search for	Provides a list of Table Dict objects
`get_tables(snapshot)`	`snapshot`: the snapshot to parse	Provides a list of Table Dict objects

`liquibase_utilities`

These functions are available to you after importing liquibase_utilities.

Utilities are general script helpers that retrieve content frequently searched for.

Function	Input Parameter	Return
`generate_sql(change)`	`change`: the change to generate SQL from	Returns the SQL associated with this change that Liquibase would deploy to your database. The function returns any inline SQL (formatted SQL or `sql` Change Type) or SQL within referenced files (`sqlFile`) it finds. Otherwise, it generates SQL from any modeled Change Types (like `createTable`) it finds, similar to running the `update-sql` command. Does not include Liquibase-specific SQL, like updates to the DATABASECHANGELOG table. Example: `changes = liquibase_utilities.get_changes() sql = liquibase_utilities.generate_sql(change[0]) if "something bad" in sql: status.fired = True sys.exit(1) # exit from the check`
`get_arg(name)`	`name`: the argument to find	Return the value of the script argument you specified while creating or customizing your check in the CLI. 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"))`.
`get_binding(key)`	`key`: the binding to access	Returns the binding object at the given key
`get_cache(key, default_value)`	`key`: the look up key `default_value`: the value to put for the key if no value present	Returns the stored key/value pairs currently held by a dict object that are available between script executions. For example, you can count the number of times a check triggers by adding a counter that updates for each feature. If there is no current value, returns the default value.
`get_changes()`		Returns the set of Liquibase change objects that the check is actively examining
`get_changeset()`		Returns the changeset object Liquibase is actively examining
`get_column_type(database_object)`	`database_object`: the database object to check	Returns the data type of the column of a database object. Examples include: `varchar`, `integer`, etc. If the database object is not a column, returns `None`.
`get_database()`		Returns the Liquibase database object
`get_database_object()`		Return the `DatabaseObject` that is being referenced in a database-scoped check
`get_database_snapshot()`		Return the `DatabaseSnapshot` object as a string
`get_dbutil()`		Return the `db_util` object used to check for object existence or to snapshot the `DatabaseObject` and return it
`get_logger()`		Return the Liquibase logger
`get_object_type_name(database_object)`	`database_object`: the `database_object` to return the type for	Return the object type of a given database object as a string
`get_script_message()`		Return the message for the script. This is the message you specify in the CLI when you create a custom policy check.
`get_script_path()`		Return the path of the script. This is the path you specify in the CLI when you create a custom policy check.
`get_snapshot()`		Return the snapshot as a JSON object. If no snapshot is available, return `None`.
`get_status()`		Return the `Status` object, which is used to set the check fired status and return a message. Required to tell Liquibase whether a check has triggered.
`has(object_type, schema_name, object_name)`	`object_type`: the object type `schema_name`: the schema name `object_name`: the object name	Returns `true` if there is an object of this type and name in the schema, `false` otherwise
`has_relation(object_type, object_name, relation_type, relation_schema_name, relation_name)`	`object_type`: the object type `object_name`: the object name `relation_type`: the type of relation (Table or View) `relation_schema_name`: the schema of the relation object `relation_name`: the name of the relation	Returns `true` if there is an object of this type that has a relation object that matches the relation type, schema, and name. Returns `false` if no items match the provided criteria.
`is_catalog(database_object)`	`database_object`: the database object to check	Returns `true` if the database object is a catalog, `false` otherwise
`is_check_constraint(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a check constraint, `false` otherwise
`is_column(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a column, `false` otherwise
`is_database_package(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a database package, `false` otherwise
`is_database_package_body(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a database package body, `false` otherwise
`is_foreign_key(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a foreign key, `false` otherwise
`is_function(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a function, `false` otherwise
`is_index(database_object)`	`database_object`: the database object to check	Return `true` if the database object is an index, `false` otherwise
`is_primary_key(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a primary key, `false` otherwise
`is_schema(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a schema, `false` otherwise
`is_sequence(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a sequence, `false` otherwise
`is_stored_database_logic(database_object)`	`database_object`: the database object to check	Return `true` if the database object is stored database logic, `false` otherwise
`is_stored_procedure(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a stored procedure, `false` otherwise
`is_synonym(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a synonym, `false` otherwise
`is_table(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a table, `false` otherwise
`is_trigger(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a trigger, `false` otherwise
`is_unique_constraint(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a unique constraint, `false` otherwise
`is_view(database_object)`	`database_object`: the database object to check	Return `true` if the database object is a view, `false` otherwise
`put_cache(key, value)`	`key`: the key to use `value`: the value to put in the cache	Places the stored key/value pairs held by a dict object that are available between script executions.
`query_for_list(sql, sql_file, end_delimiter)`	`sql`: the SQL to execute `sql_file`: the SQL file to execute `end_delimiter`: the end delimiter to use	Executes a SQL statement or script. Returns the result of the SQL as a list
`snapshot_object(object_type, object_name, relation_type, schema_name, relation_name)`	`object_type:` the type of the object, like Table `object_name`: the objects name `relation_type`: a type of relation that we need to snapshot to access the object `schema_name`: the schema for the relation `relation_name`: the name of the relation	Returns a Liquibase model object that represents the database object specified
`split_sql(sql_string, strip_comments_flag, end_delimiter, changeset)`	`sql_string`: the SQL to process `strip_comments_flag`: set to `true` to strip out comments `end_delimiter`: the end delimiter to use while processing the SQL `changeset`: the change set associated with the SQL	Returns an array of SQL lines
`split_statements(sql_string)`	`sql_string`: the SQL string to split	Splits a string of SQL into individual statements. Returns the list of SQL strings
`strip_comments(sql_string)`	`sql_string`: the SQL to strip	Strips comments from a SQL string. Returns the SQL string with comments removed
`tokenize(statement)`	`statement`: the statement to tokenize	Tokenizes a statement which was created by the `sqlparse` Python module. Returns the tokenized statement as a list

`liquibase_constants`

These functions are available to you after importing liquibase_constants.

Constants are an unchangeable set of well-known constants that are used to access the script bindings. They are definitions of internal Python classes Liquibase uses to enable custom policy checks via Python scripts.

Warning: You should be familiar with what a Python class is and how classes can have variables which are the equivalent of a constant. Most users will not need to use these unless you are debugging a complex custom policy check you have created.

`Constant` methods

__init__(self)
__setattr__(self, name, value)

`Constant` data descriptors

__dict__
__weakref__

`ScriptConstant` data descriptors

__dict__
__weakref__

`ScriptConstant` data and other attribute definitions

ARGS_SUFFIX = '_arg_binding'
CACHE_BINDING = 'cache_binding'
CHANGESET_BINDING = 'changeSet_binding'
CHANGES_BINDING = 'changes_binding'
DATABASE_BINDING = 'database_binding'
DATABASE_OBJECT_BINDING = 'databaseObject_binding'
DATABASE_SNAPSHOT_BINDING = 'databaseSnapshot_binding'
DBUTIL_BINDING = 'dbutil_binding'
LOGGER_BINDING = 'logger_binding'
SCRIPT_MESSAGE_BINDING = 'scriptMessage_binding'
SCRIPT_PATH_BINDING = 'script_path_binding'
STATUS_BINDING = 'status_binding'

Liquibase Python Modules

Python modules

Import syntax

liquibase_changesets

liquibase_database

liquibase_json

liquibase_utilities

liquibase_constants

Constant methods

Constant data descriptors

ScriptConstant data descriptors

ScriptConstant data and other attribute definitions