What are Liquibase custom change types and how do you create one?

When Liquibase's built-in change types do not cover a specific requirement, you can create a custom change by implementing the CustomChange (or CustomSqlChange for SQL-generating changes) interface. This lets you write Java logic that runs as part of a migration — useful for complex data transformations, calling external APIs during migration, or any operation that requires conditional logic beyond what Liquibase XML can express.

Implementing a custom change:

public class MigrateEncryptedPasswordsChange implements CustomChange {

    private String tableName;

    // Liquibase sets this via reflection using <param name="tableName" value="user"/>
    public void setTableName(String tableName) {
        this.tableName = tableName;
    }

    @Override
    public void execute(Database database) throws CustomChangeException {
        try (Connection conn = ((JdbcConnection) database.getConnection()).getUnderlyingConnection()) {
            // Custom Java logic: read rows, re-encrypt passwords, write back
            // ...
        } catch (Exception e) {
            throw new CustomChangeException("Password migration failed", e);
        }
    }

    @Override
    public String getConfirmationMessage() {
        return "Encrypted passwords migrated for table " + tableName;
    }

    @Override
    public void setUp() throws SetupException {}

    @Override
    public void setFileOpener(ResourceAccessor resourceAccessor) {}

    @Override
    public ValidationErrors validate(Database database) { return new ValidationErrors(); }
}

In the changeLog:

<changeSet id="migrate-passwords" author="ivan">
    <customChange class="com.example.MigrateEncryptedPasswordsChange">
        <param name="tableName" value="user"/>
    </customChange>
</changeSet>

Custom changes must also implement rollback logic if they define a <rollback> block, or they can implement CustomSqlRollback. For SQL-generating changes, implementing CustomSqlChange is preferable because Liquibase can then generate the SQL for the updateSQL preview command.

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.