What is the drift report?
Last updated: July 14, 2025
The drift report is a Liquibase operation report that informs you of database drift.
Database drift occurs when changes to one database are not made to others – often when manual changes are made outside of automation. These inconsistencies are challenging to detect. Once detected, tracking down the problem is manual, frustrating, and takes time.
If you're working in an environment that experiences database drift, Liquibase drift reports can alert you of the drift and show you the changes that need to be addressed. This simplifies the process and minimizes the amount of time databases are out of sync.
In Liquibase 4.25.0 and later, you can automatically generate a database drift report using the Liquibase diff command. 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.
In 4.25.1 and later, you can also generate a drift report with the diff-changelog command.
It is best practice to explicitly set a drift severity level that matches your team's expectation of allowable drift.
Uses
Using Liquibase drift detection can help developers, DBAs, DevOps engineers, and managers in the following ways:
Easily scan and understand differences with summary of differences section.
Quickly identify and remediate differences with highlighted object differences.
Collaborate with your team to troubleshoot differences with new shareable report.
Examples
Setting parameters
You can modify the driftreport 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=06.diff_report.html \
diff \
--drift-severity=4 \
--reference-url="offline:sqlserver?snapshot=mySnapshot.json"
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 What parameters can I use with operation reports?
Disable reports by default; enable only the drift report
If you want to keep reports disabled by default and enable only the drift report, you can use the command parameter --report-enabled
(singular) on the diff
and diff-changelog
commands. For example:
liquibase diff \
--report-enabled=true \
--report-name=my_drift_report.html
Halt deployment if any drift is detected
liquibase
--reports-enabled=true
diff
--drift-severity=4
Log missing or unexpected objects, but ignore changed objects
liquibase
--reports-enabled=true
diff
--drift-severity-changed=0
--drift-severity-missing=2
--drift-severity-unexpected=2
Another way to specify this is to explicitly set --drift-severity-missing
and --drift-severity-unexpected
to 2
and not specify a value for --drift-severity-changed
, so it remains at its default value of 0
.
liquibase
--reports-enabled=true
diff
--drift-severity-missing=2
--drift-severity-unexpected=2
A third way to specify this is by setting --drift-severity
to 2
as a default for all drift and then overriding it only for changed objects:
liquibase
--reports-enabled=true
diff
--drift-severity=2
--drift-severity-changed=0
Parameters
Our What parameters can I use with the operations report? article contains all parameters that you can use for the operations report.
Troubleshooting
If you experience performance issues while generating drift reports, such as an OutOfMemoryError
exception, see the solutions described on Memory Limits of Inspecting Large Schemas.