Comparing Database Schema States with Liquibase — diff & diffChangeLog Explained

Content updated September 2025

Key Takeaways

• Liquibase’s diff command enables you to compare two database schema states—ideal for identifying drift, missing objects, or unexpected changes.
• You can capture a snapshot of a database before changes and then compare it to the current state to validate modifications.
• The diffChangeLog command generates an executable changelog containing the necessary changes between two states, helping you apply updates safely and consistently.
• These tools are invaluable for troubleshooting unexpected changes and maintaining schema consistency across environments.
• Combining snapshots with diff tools offers a powerful, automated workflow for database schema validation and change management.

‍

Comparing Two States of the Same Database Schema

Using Liquibase diff commands lets you quickly and safely compare two database schema states. These commands are essential when you need to check for unexpected changes. For example, after adding two tables to your database, you might want to confirm that the change went as planned. The diff command shows you exactly what changed, so you can spot issues early and resolve them before they impact your team. See our Best Practices for Using Diffs.

Even better, if you know that you want to apply the schema from the database that you know has the state you want, you can create a deployable changelog with the differences between the two states using the diffChangeLog command.

Many times, developers use these commands across several different environments. But what if there is currently just one environment being worked on that needs to be examined? It feels like you would only have one schema, so what do you compare it with? I’ll walk you through the steps you can take to compare the state you have with the state you want and then apply the changes with Liquibase.

Workflow

1. Take a snapshot of the database schema prior to making the changes.

liquibase --defaultSchemaName=schema_dev --outputFile=schema_dev_before.json snapshot --snapshotFormat=json

2. Apply any schema changes as usual.

3. Run the diff command.

The diff command compares the snapshot schema_dev_before.json with your current schema schema_dev.

liquibase --url=offline:oracle?snapshot=schema_dev_before.json --referenceUrl=jdbc:oracle:thin:@hostname.net:1521:myServiceName --referenceDefaultSchemaName=schema_dev diff

4. Check for differences.

You’ll get a list of all differences between the snapshot and your current schema. For example, if you added a table called “newtable,” the diff output will show that.

Missing Table(s):
newtable

5. If desired, write these differences in a deployable changelog.

Use the diffChangeLog command to generate a changelog with the differences as changesets.

liquibase --url=offline:oracle?snapshot=schema_dev_before.json --referenceUrl=jdbc:oracle:thin:@hostname.net:1521:myServiceName --referenceDefaultSchemaName=schema_dev
--changeLogFile=schema_dev_diff.xml diffChangeLog

6. Update the original schema.

Use the liquibase update command to apply the new changelog to the original schema.

Summing it up

Liquibase offers powerful comparison features that fit into many workflows. By automating and standardizing database change management, you can move faster, reduce errors, and maintain control across all your environments. If you have questions or need help, visit our forum or our Discord chat room. 

If you want to learn more, check out our product tour.

‍

Frequently Asked Questions

Q1: What exactly is the diff command in Liquibase?

The diff command compares two database schema states (live databases or snapshots) and reports differences, such as missing, unexpected, or changed objects.

Q2: How do I compare a schema before and after changes?

First, take a snapshot of the original schema using snapshot. After changes, run diff to compare the snapshot against the current database state.

Q3: What is diffChangeLog used for?

diffChangeLog automatically generates a changelog file with changes between two database states, producing a deployable set of changesets.

Q4: When should I use these commands?

Use diff and diffChangeLog for verifying that expected changes are recorded, detecting drift between environments, and generating changelogs when developers lacked proper change-tracking processes.

Q5: Are there limitations or things to watch out for?

Yes—diff tools don’t understand semantic intent. For example, a renamed column may appear as a deletion and re-addition, potentially causing data loss if not manually reviewed. Use diffs as validation tools, not as your sole change management strategy.

‍