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.

Different 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.

Report types

Report type	Report description	Command	Liquibase versions
Checks Report	This checks report provides data about the execution of Liquibase Policy Checks.	`checks run`	4.26.0+
Drift Report	The drift report shows the differences between two live databases or between a database and a snapshot from a previous point in time.	`diff`	4.25.0+
Drift Report		`diff-changelog`	4.25.1+
Update Report	The update report informs you of system, runtime, operation, and changeset information about your database deployments.	`update` `update-count` `update-one-changeset` `update-to-tag`	4.25.1+
Update Report		`update-testing-rollback`	4.28.0+
Rollback Report	The rollback report informs you of system, runtime, operation, and changeset information about your database rollbacks.	`rollback` `rollback-count` `rollback-one-changeset` `rollback-one-update` `rollback-to-date`	4.27.0+
Rollback Report		`update-testing-rollback`	4.28.0+

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 a supported command, Liquibase always generates a report
- Selectively generate reports at runtime:
  - Command line: liquibase --reports-enabled=true <command>
  - JVM system property: JAVA_OPTS="-Dliquibase.reports.enabled=true" liquibase <command>

Note: To enable or disable only a specific kind of report, such as the drift report, you can set the liquibase.command.<cmdName>.reportEnabled parameter. See the pages linked in the Report types section.

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: `true`.	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-open=<true\|false>`	Boolean	Specifies whether to automatically open the report in your default browser at the global level. Overridden by `--report-open` at the command level. Default: `true`.	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
`--reports-suppress-exception=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from operation reports at the global level. Overridden by `--report-suppress-exception` at the command level. Default: `false`. However: If `--reports-suppress-exception` is not set and `--reports-suppress-sql=true`, Liquibase suppresses all SQL, including exception SQL. If `--reports-suppress-exception=false` and `--reports-suppress-sql=true`, Liquibase suppresses most SQL but shows exception SQL.	Optional
`--reports-suppress-sql=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the global level. Overridden by `--report-suppress-sql` at the command level. Default: `false`.	Optiona

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: `true`.	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-open: "<true\|false>" }`	Boolean	Specifies whether to automatically open the report in your default browser at the global level. Overridden by `--report-open` at the command level. Default: `true`.	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
`globalArgs: { reports-suppress-exception: "<true\|false>" }`	Boolean	Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from operation reports at the global level. Overridden by `--report-suppress-exception` at the command level. Default: `false`. However: If `--reports-suppress-exception` is not set and `--reports-suppress-sql=true`, Liquibase suppresses all SQL, including exception SQL. If `--reports-suppress-exception=false` and `--reports-suppress-sql=true`, Liquibase suppresses most SQL but shows exception SQL.	Optional
`globalArgs: { reports-suppress-sql: "<true\|false>" }`	Boolean	Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the global level. Overridden by `--report-suppress-sql` at the command level. Default: `false`.	Optiona

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: `true`.	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.open: <true\|false>`	Boolean	Specifies whether to automatically open the report in your default browser at the global level. Overridden by `--report-open` at the command level. Default: `true`.	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
`liquibase.reports.suppressException: <true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from operation reports at the global level. Overridden by `--report-suppress-exception` at the command level. Default: `false`. However: If `--reports-suppress-exception` is not set and `--reports-suppress-sql=true`, Liquibase suppresses all SQL, including exception SQL. If `--reports-suppress-exception=false` and `--reports-suppress-sql=true`, Liquibase suppresses most SQL but shows exception SQL.	Optional
`liquibase.reports.suppressSql: <true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the global level. Overridden by `--report-suppress-sql` at the command level. Default: `false`.	Optiona

Parameter	Type	Description	Requirement
`JAVA_OPTS=-Dliquibase.reports.enabled=<true\|false>`	Boolean	Enables or disables all reports at the global level. Overridden by `--report-enabled` at the command level. Default: `true`.	Required (either this or `--report-enabled`)
`JAVA_OPTS=-Dliquibase.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
`JAVA_OPTS=-Dliquibase.reports.open=<true\|false>`	Boolean	Specifies whether to automatically open the report in your default browser at the global level. Overridden by `--report-open` at the command level. Default: `true`.	Optional
`JAVA_OPTS=-Dliquibase.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
`JAVA_OPTS=-Dliquibase.reports.suppressException=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from operation reports at the global level. Overridden by `--report-suppress-exception` at the command level. Default: `false`. However: If `--reports-suppress-exception` is not set and `--reports-suppress-sql=true`, Liquibase suppresses all SQL, including exception SQL. If `--reports-suppress-exception=false` and `--reports-suppress-sql=true`, Liquibase suppresses most SQL but shows exception SQL.	Optional
`JAVA_OPTS=-Dliquibase.reports.suppressSql=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the global level. Overridden by `--report-suppress-sql` at the command level. Default: `false`.	Optiona

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: `true`.	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_OPEN=<true\|false>`	Boolean	Specifies whether to automatically open the report in your default browser at the global level. Overridden by `--report-open` at the command level. Default: `true`.	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
`LIQUIBASE_REPORTS_SUPPRESS_EXCEPTION=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide exceptions (which may contain SQL) from operation reports at the global level. Overridden by `--report-suppress-exception` at the command level. Default: `false`. However: If `--reports-suppress-exception` is not set and `--reports-suppress-sql=true`, Liquibase suppresses all SQL, including exception SQL. If `--reports-suppress-exception=false` and `--reports-suppress-sql=true`, Liquibase suppresses most SQL but shows exception SQL.	Optional
`LIQUIBASE_REPORTS_SUPPRESS_SQL=<true\|false>`	Boolean	Liquibase 4.31.0+. Specifies whether to hide changeset SQL in operation reports at the global level. Overridden by `--report-suppress-sql` at the command level. Default: `false`.	Optiona

Command parameters

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

For a list of command parameters related to operation reports, such as parameters for the drift report, see the individual report pages listed in the Report types section.

Troubleshooting

If operation reports fail to generate, Liquibase displays error messages but does not halt execution.

Read/write permissions

If you lack the necessary read/write permissions to generate a report, you may receive this error message:

INFO: For users with appropriate permissions and access, operation reports are available by setting 
'LIQUIBASE_REPORT_PATH' to a dir with read/write capability. Suppress this message and disable report 
generation by setting the 'LIQUIBASE_REPORT_ENABLED' to false. 
Learn more at https://docs.liquibase.com/observability

To resolve this, set a value of --report-path that your system can read/write to.

Liquibase with Docker

If you use Liquibase alongside Docker, reports do not write directly to your local machine by default, they write to an output stream. When you write a report, Liquibase says a file was created, but it is not accessible from within the container. To gain access to this file, you can write reports to a directory within the Docker container or to a mounted volume.

Docker Container option:
You can specify --report-path=./ to indicate the container's current working directory which writes a report to a directory within the docker container.

Mounted volume option:
Write reports to a mounted volume by ensuring the Docker container user has the appropriate permissions to access and write to the mounted volume.

Assign write permissions to a mounted volume author by following these steps:

Use this key value:

Copy

Key Addition:
--user root
By using the --user root flag, you ensure that the container operates with elevated privileges, which may help avoid permission issues with files in the mounted directory. Use this with caution to avoid unintended changes, as the root user has unrestricted access inside the container.
Run this command:
sudo docker run --network=host --rm -v /home/path/to/changelog:/liquibase/changelog --user root liquibase-image --reports-path=/liquibase/changelog --changelog-file=changelog/changelog.xml update --url=jdbc:h2:tcp://localhost:9090/mem:dev --password=letmein --username=dbuser

Run this command: