- Concept
- Version · 6.0
- Deliver
What is the drift report?
Last updated: August 21, 2026
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:
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.
Large schemas: out-of-memory errors
In Liquibase Secure 5.2 and later, drift report generation includes two improvements for large databases. For most users, this works automatically with no configuration required. The two improvements are:
Smart report mode — If your database has more than 10,000 changed objects (by default), the report skips the most memory-intensive sections but keeps summaries and object listings. You can adjust this limit if needed.
Faster processing — Report generation is faster and more memory-efficient for smaller databases.
To control this threshold, set the liquibase.reports.drift.maxDetailedObjects property. The default is 10000.
If you are still experiencing OutOfMemoryError exceptions, lower the threshold to trigger the optimized format sooner. Add the following to your liquibase.properties file:
liquibase.reports.drift.maxDetailedObjects=5000
This tells Liquibase to use the lightweight report format when there are more than 5,000 changes (instead of waiting until 10,000).
If you need full detailed reports for large snapshots, increase the threshold. Make sure you have sufficient heap memory available:
liquibase.reports.drift.maxDetailedObjects=50000
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.
To automatically use Liquibase drift reports in your CI/CD pipeline, you'll follow these steps in your CI/CD tool.
Learn what parameters can be used with all operation reports, such as the checks, drift, update, and rollback reports.