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+
		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-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+
		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:

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:
     • 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.

Command parameters

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

For information about command parameters, 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:

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

2. Run this command:
3. Copy

   sudo docker run --network=host --rm -v /home/path/to/changelog:/liquibase/changelog --user $(id -u):$(id -g) liquibase-image --reports-path=/liquibase/changelog --changelog-file=changelog/changelog.xml update --url=jdbc:h2:tcp://localhost:9090/mem:dev --password=letmein --username=dbuser

Reports are not enabled

If you have the appropriate read/write permissions and your environment is not headless, but you have disabled operation reports, you may receive this error message:

A Pro Update Report was not created!
** To generate a Update report add command arg 'liquibase update --report-enabled=true'
** To generate all available Pro reports set liquibase.reports.enabled=true, or LIQUIBASE_REPORTS_ENABLED=true

To resolve this, set --report-enabled or --reports-enabled to true.

Related links

• Structured Logging