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 |
---|---|---|
|
Boolean | Enables or disables all reports at the global level. Overridden by --report-enabled at the command level. Default: false . |
|
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 . |
|
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 . |
|
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 errorMAJOR
(2
): drift is a major failureMINOR
(1
): drift is a minor failureINFO
(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 |
---|---|---|
|
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 . |
|
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 . |
|
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 . |
|
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 |
---|---|---|
|
Boolean | Enables a report at the command level. Overrides the global argument --reports-enabled . Default: false . |
|
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 . |
|
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 . |
|
String | Specifies the file path to the report file at the command level. Overrides the global argument --reports-path . Default: ./ . |