Checks Run Report

The checks run report is a Liquibase operation report that provides data about the execution of Liquibase Quality Checks. You can configure checks for your changelogs and database to ensure standardized and consistent behavior with Liquibase.

In Liquibase 4.26.0 and later, you can automatically generate a checks run report using the Liquibase checks run command. The checks run report gives you a human-readable summary of command metadata, warning messages, checks package and other configuration details, and an organized summary of check output. For changelog-scoped checks, the summary identifies changelogs and changesets that tripped checks, their content, and any attributes. For database-scope checked, the summary contains entries for specific objects that tripped checks and a count of object types checked. You can view summaries sorted by changeset, database, and individual check.

Uses

Using Liquibase checks run reports can help developers, DBAs, DevOps engineers, and managers in the following ways:

• Easily scan and understand which checks have run and their results with the summary section
• Analyze your checks by viewing results by changeset, check, and database
• Collaborate with your team with shareable reports

Enable operation reports

To enable all operation reports, you must:

1. Set the --license-key property using your Liquibase Pro license key.
2. Choose how often to generate reports. You can either:
   • Always generate reports:
     • liquibase.properties file: liquibase.reports.enabled=true
     • Environment variable: LIQUIBASE_REPORTS_ENABLED=true
     • Then, when you run liquibase checks run, Liquibase always generates a report
   • Selectively generate reports at runtime:
     • Command line: liquibase --reports-enabled=true checks run
     • JVM system property: JAVA_OPTS="-Dliquibase.reports.enabled=true" liquibase checks run

Checks run reports in automation

To automatically use Liquibase checks run reports in your CI/CD pipeline, follow these steps in your CI/CD tool:

1. Create a LiquibaseChecksRunReport job that generates the checks run report. This job must:
   1. Enable the checks run report with --reports-enabled (global scope) or --report-enabled (command scope).
   2. Run the Liquibase checks run command against your changelogs and/or database.

   Tip: For more information, see the Examples section of this page.

Examples

Setting parameters

You can modify the checks run report output with the parameters listed in the tables on this page. In the CLI, global parameters go to the left of the command and command parameters go to the right of the command.

liquibase \
    --reports-enabled=true \
    --reports-path=reports \
    --reports-name=checks_run_report.html \
  checks run \
    --changelog-file="example-changelog.xml"

Note: For readability, this page shows parameters on new lines. If you type in the commands on a single line, do not include the backslashes \ shown in the examples.

You can also set parameters in your liquibase.properties file, as environment variables, or in a flow file. For a list of parameters and their syntax in each format, see the Global parameters and Command parameters sections of this page.

Disable reports by default; enable only the checks run report

If you want to keep reports disabled by default and enable only the checks run report, you can use the command parameter --report-enabled (singular) on the checks run command. For example:

liquibase checks run \
    --report-enabled=true \
    --report-name=my_checks_run_report.html

stages:
  Checks_Run_Report:
    actions:
      - type: liquibase
        command: checks run
        cmdArgs: { changelog-file: "example-changelog.xml",
                        report-format: "HTML"}
        globalArgs: { mirror-console-messages-to-log: "true",
                        reports-enabled: "true",
                        reports-path: "reports",
                        reports-name: "checks-run-report.html"}

Global parameters

Use these parameters to control the behavior of all operation reports.

Note: Syntax for each parameter is specified in kebab-case (CLI and flow file), camelCase (properties file and JAVA_OPTS), and MACRO_CASE (environment variable).

--reports-enabled
globalArgs: {reports-enabled: "val"}
liquibase.reports.enabled
LIQUIBASE_REPORTS_ENABLED

--reports-name
globalArgs: {reports-name: "val"}
liquibase.reports.name
LIQUIBASE_REPORTS_NAME

--reports-path
globalArgs: {reports-path: "val"}
liquibase.reports.path
LIQUIBASE_REPORTS_PATH

Command parameters

Use these command parameters if you want to specify operation report behavior for a specific command.

--report-enabled
cmdArgs: {report-enabled: "val"}
liquibase.command.<cmdName>.reportEnabled
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_ENABLED

--open-report
cmdArgs: {open-report: "val"}
liquibase.command.<cmdName>.openReport
LIQUIBASE_COMMAND_<CMDNAME>_OPEN_REPORT

--report-name
cmdArgs: {report-name: "val"}
liquibase.command.<cmdName>.reportName
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_NAME

--report-path
cmdArgs: {report-path: "val"}
liquibase.command.<cmdName>.reportPath
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_PATH