Checks Report

Graphical output of checks report. Contains a warning about critical errors followed by a runtime summary and other details.

The checks report is a Liquibase operation report that provides data about the execution of Liquibase Policy 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 report using the Liquibase checks run command. The checks report gives you an easy-to-read, sharable summary of command metadata, warning messages, check severity levels, checks packages, and configuration details, plus an organized summary of check output in a browser page. 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 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

In Liquibase 4.29.0 and later, operation reports are enabled by default.

In older versions, operation reports are disabled by default. 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:
    • Selectively generate reports once at runtime:
      • Command line: liquibase checks run --report-enabled=true
      • Environment variable: LIQUIBASE_COMMAND_ROLLBACK_REPORT_ENABLED=true
      • JVM system property: JAVA_OPTS="-Dliquibase.report.enabled=true" liquibase checks run

Checks reports in automation

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

  1. Create a LiquibaseChecksReport job that generates the checks report. This job must:
    1. Enable the checks 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 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 report

If you want to keep reports disabled by default and enable only the checks 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

This is an example flow file running a checks report:

stages:
  Checks_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-report.html"}

Note: This example uses reports-enabled (plural) within globalArgs to enables all operation reports. To enable this specific kind of report, but not other reports, you must instead set report-enabled (singular) in cmdArgs.

Parameters

Global parameters

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

Parameter Type Description Requirement

--reports-enabled=<true|false>

Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. Required (either this or --report-enabled)

--reports-name=<string>

String Specifies the name of the report file at the global level. Overridden by --report-name at the command level. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html. Optional

--reports-path=<string>

String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./ Optional

Command parameters

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

Parameter Type Description Requirement

--report-enabled=<true|false>

Boolean

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Required (either this or --reports-enabled)

--report-name=<string>

String

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

Optional

--report-open=<true|false>

Boolean

If true, automatically opens the report in your default browser. Default: false.

Note: Prior to Liquibase 4.29.0, this parameter was called --open-report instead of --report-open.

Optional

--report-path=<string>

String

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional

Global parameters

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

Parameter Type Description Requirement

globalArgs: { reports-enabled: "<true|false>" }

Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. Required (either this or --report-enabled)

globalArgs: { reports-name: "<string>" }

String Specifies the name of the report file at the global level. Overridden by --report-name at the command level. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html. Optional

globalArgs: { reports-path: "<string>" }

String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./ Optional

Command parameters

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

Parameter Type Description Requirement

cmdArgs: { report-enabled: "<true|false>" }

Boolean

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Required (either this or --reports-enabled)

cmdArgs: { report-name: "<string>" }

String

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

Optional

cmdArgs: { report-open: "<true|false>" }

Boolean

If true, automatically opens the report in your default browser. Default: false.

Note: Prior to Liquibase 4.29.0, this parameter was called --open-report instead of --report-open.

Optional

cmdArgs: { report-path: "<string>" }

String

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional

Global parameters

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

Parameter Type Description Requirement

liquibase.reportsEnabled: <true|false>

Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. Required (either this or --report-enabled)

liquibase.reportsName: <string>

String Specifies the name of the report file at the global level. Overridden by --report-name at the command level. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html. Optional

liquibase.reportsPath: <string>

String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./ Optional

Command parameters

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

Parameter Type Description Requirement

liquibase.command.reportEnabled: <true|false>

liquibase.command.checks.run.reportEnabled: <true|false>

Boolean

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Required (either this or --reports-enabled)

liquibase.command.reportName: <string>

liquibase.command.checks.run.reportName: <string>

String

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

Optional

liquibase.command.reportOpen: <true|false>

liquibase.command.checks.run.reportOpen: <true|false>

Boolean

If true, automatically opens the report in your default browser. Default: false.

Note: Prior to Liquibase 4.29.0, this parameter was called --open-report instead of --report-open.

Optional

liquibase.command.reportPath: <string>

liquibase.command.checks.run.reportPath: <string>

String

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional

Global parameters

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

Parameter Type Description Requirement

JAVA_OPTS=-Dliquibase.reportsEnabled=<true|false>

Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. Required (either this or --report-enabled)

JAVA_OPTS=-Dliquibase.reportsName=<string>

String Specifies the name of the report file at the global level. Overridden by --report-name at the command level. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html. Optional

JAVA_OPTS=-Dliquibase.reportsPath=<string>

String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./ Optional

Command parameters

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

Parameter Type Description Requirement

JAVA_OPTS=-Dliquibase.command.reportEnabled=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.reportEnabled=<true|false>

Boolean

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Required (either this or --reports-enabled)

JAVA_OPTS=-Dliquibase.command.reportName=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.reportName=<string>

String

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

Optional

JAVA_OPTS=-Dliquibase.command.reportOpen=<true|false>

JAVA_OPTS=-Dliquibase.command.checks.run.reportOpen=<true|false>

Boolean

If true, automatically opens the report in your default browser. Default: false.

Note: Prior to Liquibase 4.29.0, this parameter was called --open-report instead of --report-open.

Optional

JAVA_OPTS=-Dliquibase.command.reportPath=<string>

JAVA_OPTS=-Dliquibase.command.checks.run.reportPath=<string>

String

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional

Global parameters

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

Parameter Type Description Requirement

LIQUIBASE_REPORTS_ENABLED=<true|false>

Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. Required (either this or --report-enabled)

LIQUIBASE_REPORTS_NAME=<string>

String Specifies the name of the report file at the global level. Overridden by --report-name at the command level. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html. Optional

LIQUIBASE_REPORTS_PATH=<string>

String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./ Optional

Command parameters

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

Parameter Type Description Requirement

LIQUIBASE_COMMAND_REPORT_ENABLED=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_ENABLED=<true|false>

Boolean

Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false.

Required (either this or --reports-enabled)

LIQUIBASE_COMMAND_REPORT_NAME=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_NAME=<string>

String

Specifies the name of the report file at the command level. Overrides the global argument --reports-name. By default, Liquibase generates a new report file labeled with a timestamp (user's local time). If you set a custom name, Liquibase overwrites the existing file every time you generate a new report. Default: report-<DD-Mon-YYYY-HHmmss>.html.

Optional

LIQUIBASE_COMMAND_REPORT_OPEN=<true|false>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_OPEN=<true|false>

Boolean

If true, automatically opens the report in your default browser. Default: false.

Note: Prior to Liquibase 4.29.0, this parameter was called --open-report instead of --report-open.

Optional

LIQUIBASE_COMMAND_REPORT_PATH=<string>

LIQUIBASE_COMMAND_CHECKS_RUN_REPORT_PATH=<string>

String

Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Optional