Update Report

The Liquibase CLI input and output of a deployment (runtime summary) followed by changeset execution details.

The update report is a Liquibase operation report that informs you of system, runtime, operation, and changeset information about your database deployments.

In Liquibase 4.25.1 and later, you can automatically generate a database update report using the Liquibase update family of commands: update, update-count, update-one-changeset, and update-to-tag. In Liquibase 4.28.0 and later, you can also generate an update report as part of the update-testing-rollback command.

The update report gives you a human-readable summary of the state of your database and changelogs, any generated SQL for changesets, whether the operation was successful, any error messages, and other useful data.

Uses

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

Easily scan and understand the changes made to your database with the summary section, then dive deeper with the execution details
Audit and report on the changes to your database without needing to analyze or interpret logs
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:

Set the --license-key property using your Liquibase Pro license key.
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 update, Liquibase always generates a report
- Selectively generate reports once at runtime:
  - Command line: liquibase update --report-enabled=true
  - Environment variable: LIQUIBASE_COMMAND_ROLLBACK_REPORT_ENABLED=true
  - JVM system property: JAVA_OPTS="-Dliquibase.report.enabled=true" liquibase update

Update reports in automation

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

Create a LiquibaseUpdateReport job that generates the update report. This job must:
1. Enable the update report with --reports-enabled (global scope) or --report-enabled (command scope).
2. Run a Liquibase update* command against your database.
Tip: For more information, see the Examples section of this page.

Examples

Setting parameters

You can modify the update 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=update_report.html \
  update \
    --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 update report

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

CLI example
Flow file example

liquibase update \
    --report-enabled=true \
    --report-name=my_update_report.html

This is an example flow file running a update report:

stages:
  Update_Report:
    actions:
      - type: liquibase
        command: update
        cmdArgs: { changelog-file: "example-changelog.xml",
                        report-format: "HTML"}
        globalArgs: { mirror-console-messages-to-log: "true",
                        reports-enabled: "true",
                        reports-path: "reports",
                        reports-name: "update-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.