What is the Liquibase Pro checksum validity and how do clearCheckSums and validChecksums work?

Liquibase computes an MD5 checksum for each changeSet when it first runs and stores it in DATABASECHANGELOG. On every subsequent run, Liquibase recomputes the checksum from the current file and compares it against the stored value. If they differ, Liquibase throws a ValidationFailedException and refuses to proceed.

This is a deliberate safety mechanism — if someone edits an applied changeSet, you know immediately. However, there are legitimate cases where you need to update a checksum without re-running the migration:

clearCheckSums — Clears all stored checksums in DATABASECHANGELOG, setting them to NULL. On the next run, Liquibase recomputes checksums from the current files and stores them again. This is a brute-force fix but it means Liquibase loses its ability to detect modifications until the checksums are re-stored on the next run.

liquibase clearCheckSums

validCheckSums — A more targeted approach. You declare additional valid checksums for a specific changeSet in the changeLog itself, telling Liquibase to accept any of those checksum values as legitimate. This is used when a changeSet content changed due to whitespace normalisation, encoding changes, or Liquibase version upgrades that changed how checksums are computed:

<changeSet id="1" author="alice">
    <validCheckSum>8:abc123...</validCheckSum>  <!-- previous computed checksum -->
    <createTable tableName="customer">
        ...
    </createTable>
</changeSet>

The validCheckSum child element accepts the old checksum string and tells Liquibase that this old hash is also acceptable. This is less disruptive than clearCheckSums because it only affects the specific changeSet, not the entire migration history.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.