Set Up a Custom Python Virtual Environment for Liquibase Policy Checks

Note: Download a GraalPy release that provides Python 3.12, which is GraalPy 25.0, 25.1, or 25.2. The latest GraalPy release may provide a newer Python version, and Liquibase Secure 6.0 cannot use a virtual environment built with it.

1. Download and extract GraalPy on your machine. You must use the GraalPy runtime to create the virtual environment, not the Python runtime.

2. Update your PATH environment variable to include the path to the GraalPy /bin directory you just installed.

3. In your command line, invoke GraalPy to run the venv module to create a virtual environment in the directory you specify.

graalpy -m venv <path_to_venv>

Your command line won't display anything, but this creates some scripts. You may have to wait a few seconds for the command to execute before you can type in the terminal again.

Note: Some terminals may display: "WARNING: Unable to create a system terminal, creating a dumb terminal (enable debug logging for more information)." You can ignore this.

1. Activate the virtual environment.

• Windows CMD and PowerShell: <path_to_venv>\Scripts\activate

• Windows GitBash: source <path_to_venv>/Scripts/activate

• Unix: source <path_to_venv>/bin/activate

2. Configure your IDE to recognize your custom virtual environment.

• VS Code: Python environments in VS Code

• PyCharm: Configure a virtualenv environment

3. Install modules and packages using pip.

pip install liquibase-checks-python simplejson sqlparse urllib3

When complete, the terminal displays:

Successfully installed liquibase-checks-python-<x.y.z> simplejson-<x.y.z> sqlparse-<x.y.z> urllib3-<x.y.z>

Note: You must install liquibase-checks-python to access the Liquibase API, and you must install sqlparse to run the Liquibase modules.

4. Deactivate the virtual environment.

• Windows GitBash, Windows PowerShell, and Unix: deactivate

• Windows CMD: exit

1. Use the Liquibase parameter --script-python-executable-path to provide Liquibase the path to the GraalPy Python executable in your virtual environment.

2. In your Python file, ensure that any imports of modules come from your custom virtual environment instead of the built-in virtual environment in the Liquibase Checks extension JAR.

Replaceimport <module> withfrom liquibase_checks_python import <module>.

For example:

# import Liquibase modules containing useful functions from liquibase_checks_python import liquibase_utilities as lb import sys # define reusable variables obj = lb.get_database_object() # database object to examine liquibase_status = lb.get_status() # Status object of the check # write check logic # this condition checks if the current object is a table # and whether it starts with the prefix 'tbl_' if lb.is_table(obj) and not obj.getName().lower().startswith("tbl_"): # indicate that the custom check has been triggered liquibase_status.fired = True # set the message for Liquibase to return when check is triggered liquibase_status.message = "Tables must start with the prefix tbl_. Add this prefix." # halt execution of the script sys.exit(1) # default return code False

You have now successfully configured your virtual environment for Liquibase policy checks.

If you restart your IDE, you should also see auto-complete prompts for Liquibase Python modules.

If you haven't yet run any Liquibase policy checks commands to configured your Python script as a check, follow the steps on Create a Custom Policy Check.

If you've already configured your custom policy check, you can now run it using your new virtual environment.

Be sure to:

• Replace <path/to/venv> with the path to your virtual environment.

• Replace your_python_check with your check-name.

If you specified --script-python-executable-path in your liquibase.properties file or as an environment variable, you don't need to specify it at runtime.

Note: If you don't specify a custom virtual environment to use, Liquibase runs your script in the built-in virtual environment.