Use Custom Policy Checks with Docker

This tutorial shows you how to configure Docker and Liquibase to deploy Custom Policy Checks. This helps isolate your Python scripts, minimizing conflicts with other applications on your machine.

Prerequisites

Install Docker image

  1. In your command line, install the official Liquibase Docker image:
    2. docker pull liquibase
  2. Install the Liquibase Checks extension:
    • Liquibase 4.31.0 and later: the checks extension is pre-installed in your image.
    • Liquibase 4.30.0 or earlier: you must manually add the checks extension to your image:
      • lpm add liquibase-checks

For more information, see Using Liquibase and Docker.

Configure Docker image

  1. In your Dockerfile, set necessary permissions:
    2. USER root
  2. On Linux, set the XDG_CACHE_HOME environment variable to any directory that exists and you have write permissions for:
    3. XDG_CACHE_HOME=/tmp
  3. (Optional) Create a Python Virtual Environment. Liquibase includes a built-in virtual environment in the checks extension JAR. The built-in environment contains Liquibase Python Modules and the modules simplejson, sqlparse, and urllib3. However, if you want to install additional Python libraries, you must create your own virtual environment.

Create and run your checks

  1. Follow the steps in Create a Custom Policy Check to write a basic Python check and configure it in the Liquibase checks framework.
  2. Run the Liquibase checks run command. Ensure that you specify all necessary parameters. For example:
    3. docker run -e "LIQUIBASE_LOG_LEVEL=DEBUG" --network=host --rm -v /home/liquibase-project:/liquibase/changelog --user=root liquibase/liquibase --search-path=/liquibase/changelog checks run --url=jdbc:mysql://mysql-db.us-east-1.rds.amazonaws.com:3306/db --password=xxx --username=admin --changelog-file=changelog.xml --checks-scope=changelog,database --checks-settings-file=/liquibase/changelog/liquibase.checks-settings.conf --checks-scripts-enabled=true --checks-scripts-path=/liquibase/changelog

Troubleshooting

Failed to initialize execution listener class

If you try to run Liquibase custom policy checks using Docker on Linux, you may receive this error:

Unexpected error running Liquibase: Failed to initialize execution listener class.
Caused by: java.lang.reflect.InvocationTargetException
Caused by: /home/liquibase

This happens because the /home/liquibase directory may not exist in your Docker container, so GraalPy has nowhere to write output. To fix this, you must set your XDG_CACHE_HOME environment variable to any directory that exists and you have write permissions for, such as /tmp. For example:

docker run --rm --env XDG_CACHE_HOME=/tmp --env LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCRIPTS_ENABLED='true' -v <path/to/changelog>:/liquibase/changelog -v C:\Liquibase\Demos\CPCs\lib:/liquibase/lib liquibase/liquibase:latest sh -c "liquibase checks run"

Alternatively, you can use the -v flag to mount a directory on your machine to /home/liquibase in your Docker container:

docker run --rm --env LIQUIBASE_COMMAND_CHECKS_RUN_CHECKS_SCRIPTS_ENABLED='true' -v <path/to/changelog>:/liquibase/changelog -v <path/to/liquibase/lib>:/liquibase/lib -v  <path/to/changelog>:/home/liquibase liquibase/liquibase:latest sh -c "liquibase checks run"

Next steps