Operation Reports

You can use Liquibase Pro to generate reports of operations you perform on your database. These reports contain information about the status of your database and may help you resolve errors in your automation pipeline.

Reports may include information about database drift, your database type and version, whether your database change occurred live or in a snapshot; object data about tables, views, functions, procedures, packages/package bodies, and triggers; and object relationships on constraints, indexes, and privileges.

Currently, the only command that supports operation reports is diff, which you can use to generate a report of database drift.

Drift report

Databases may experience drift (unexpected changes to content) during development. Monitoring database drift manually requires you to write extra scripts outside Liquibase to detect improper database state changes. These scripts may be difficult to maintain or prone to errors.

In Liquibase 4.23.1+, you can automatically generate a database drift report using the Liquibase command diff. The drift report shows the differences between two live databases or between a database and a snapshot from a previous point in time. Adding this check to your CI/CD pipeline gives you ongoing visibility into database drift while maintaining the speed and reliability of CI/CD automation.

It is a best practice to explicitly set a drift severity level to match your team's expectation of allowable drift.

Enable operation reports

To enable operation reports, you must set the --license-key property using your Liquibase Pro license key.

You can enable operation reports for all supported commands by setting the --reports-enabled global argument to true in your command line, in your liquibase.properties file, as an environment variable, or as a JVM system property using the JAVA_OPTS Environment Variable. This way, Liquibase always generates operation reports for you. For example:

  • Command line: liquibase --reports-enabled=true diff
  • liquibase.properties file: liquibase.reports.enabled=true
  • Environment variable: LIQUIBASE_REPORTS_ENABLED=true

You can modify the report output file with global arguments listed in the table on this page. You can also set global arguments for specific kinds of reports, like the drift report:

liquibase --reports-enabled=true --drift-severity=WARN diff

If you want to keep reports disabled by default and enable them only when you run certain commands, you can use the command argument --report-enabled (singular). For example:

liquibase diff --report-enabled=true --report-name=my_drift_report.html

Global attributes

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

Name Type Description 
--reports-enabled
liquibase.reports.enabled
LIQUIBASE_REPORTS_ENABLED
 Boolean Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false. 
--reports-format
liquibase.reports.format
LIQUIBASE_REPORTS_FORMAT
 String Specifies the format of the report output file at the global level. Overridden by --report-format at the command level. Valid values are: HTML. Default: HTML. 
--reports-name
liquibase.reports.name
LIQUIBASE_REPORTS_NAME
 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-MM-YYYY-HHmmss>.html. 
--reports-path
liquibase.reports.path
LIQUIBASE_REPORTS_PATH
 String Specifies the file path to the report file at the global level. Overridden by --report-path at the command level. Default: ./.

Drift report global attributes

When Liquibase detects database drift (changed, missing, or unexpected content), it records that in your drift report. Use the --drift-severity argument to specify a severity return code for drift. The severity level you set tells Liquibase how to react when it detects drift:

  • BLOCKER (4): drift is a blocker (most severe)
  • CRITICAL (3): drift is a critical error
  • MAJOR (2): drift is a major failure
  • MINOR (1): drift is a minor failure
  • INFO (0): drift is treated as an informational message (least severe)

Use individual --drift-severity-* arguments to specify an error code for a particular kind of drift. You can use the return code as an alert in the rest of your CI/CD pipeline.

Name Type Description 
--drift-severity
liquibase.drift.severity
LIQUIBASE_DRIFT_SEVERITY
 String Specifies the severity level of all error types in the drift report (changed, missing, or unexpected content). Valid values are BLOCKER, CRITICAL, MAJOR, MINOR, and INFO; or 0–4. If both --drift-severity and one of the individual error type arguments are set, the individual error type arguments take priority. Default: INFO. 
--drift-severity-changed
liquibase.drift.severity.changed
LIQUIBASE_DRIFT_SEVERITY_CHANGED
 String Specifies the severity level of changed content in the drift report. Valid values are BLOCKER, CRITICAL, MAJOR, MINOR, and INFO; or 0–4. Overrides the value of --drift-severity for changed content only. Default: INFO. 
--drift-severity-missing
liquibase.drift.severity.missing
LIQUIBASE_DRIFT_SEVERITY_MISSING
 String Specifies the severity level of missing content in the drift report. Valid values are BLOCKER, CRITICAL, MAJOR, MINOR, and INFO; or 0–4. Overrides the value of --drift-severity for missing content only. Default: INFO. 
--drift-severity-unexpected
liquibase.drift.severity.unexpected
LIQUIBASE_DRIFT_SEVERITY_UNEXPECTED
 String Specifies the severity level of unexpected content in the drift report. Valid values are BLOCKER, CRITICAL, MAJOR, MINOR, and INFO; or 0–4. Overrides the value of --drift-severity for unexpected content only. Default: INFO.

Command attributes

Use these command arguments if you want to specify report behavior for a specific command:

Name Type Description 
--report-enabled
liquibase.command.<cmdName>.reportEnabled
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_ENABLED
 Boolean Enables a report at the command level. Overrides the global argument --reports-enabled. Default: false. 
--report-format
liquibase.command.<cmdName>.reportFormat
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_FORMAT
 String Specifies the format of the report output file at the command level. Overrides the global argument --reports-format. Valid values are: HTML. Default: HTML. 
--report-name
liquibase.command.<cmdName>.reportName
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_NAME
 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-<day-month-year-timecode>.html. 
--report-path
liquibase.command.<cmdName>.reportPath
LIQUIBASE_COMMAND_<CMDNAME>_REPORT_PATH
 String Specifies the file path to the report file at the command level. Overrides the global argument --reports-path. Default: ./.

Related links