Updating ChangeSet Checksums

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java
• src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java
• src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java
• src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java

Updating ChangeSet checksums is a critical maintenance operation within the Liquibase ClickHouse extension. It ensures that the DATABASECHANGELOG table accurately reflects the current state of applied changesets, particularly when a checksum needs to be recalculated without re-executing the migration logic. This process leverages ClickHouse's mutation capabilities to modify existing records in the tracking table.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java:47-65, src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:54-72

Architecture and Core Logic

The checksum update logic is encapsulated in the UpdateChangeSetChecksumClickHouse class, which extends the standard Liquibase UpdateChangeSetChecksumGenerator. This implementation is specifically designed to handle ClickHouse's unique SQL syntax for data mutations.

SQL Generation Flow

When a checksum update is triggered, the generator retrieves cluster configurations and constructs an ALTER TABLE ... UPDATE statement. Unlike standard relational databases that use the UPDATE command, ClickHouse requires an ALTER statement for asynchronous mutations of existing data.

The flow illustrates how the extension intercepts the standard checksum update request and converts it into a ClickHouse-compatible mutation.
Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java:42-69

Component Interaction

The update process interacts with several key components to ensure the generated SQL is correct for the specific environment (single instance vs. cluster).

Component	Responsibility
UpdateChangeSetChecksumClickHouse	Main generator logic for ClickHouse checksum updates.
ParamsLoader	Loads cluster configurations from liquibaseClickhouse.conf.
SqlGeneratorUtil	Provides utility methods for adding ON CLUSTER clauses.
ClickHouseDatabase	Identifies the database type and provides schema names.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-105, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:47-50, src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java:56-61

Mutation Implementation

The extension uses the ALTER TABLE ... UPDATE syntax with the SETTINGS mutations_sync = 1 parameter. This ensures that the update is processed synchronously, which is vital for maintaining the integrity of the Liquibase execution state.

Query Structure

The generated query targets the DATABASECHANGELOG table and identifies the specific record using a composite key:

1. ID
2. AUTHOR
3. FILENAME

String updateChecksumQuery =
    String.format(
        "ALTER TABLE `%s`.%s "
            + SqlGeneratorUtil.generateSqlOnClusterClause(properties)
            + "UPDATE MD5SUM = '%s' WHERE ID = '%s' AND AUTHOR = '%s' AND FILENAME = '%s' SETTINGS mutations_sync = 1",
        database.getDefaultSchemaName(),
        database.getDatabaseChangeLogTableName(),
        changeSet.generateCheckSum().toString(),
        changeSet.getId(),
        changeSet.getAuthor(),
        changeSet.getFilePath());

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java:58-67

Cluster Support

If the ClusterConfig is present (loaded via ParamsLoader), the extension automatically appends the ON CLUSTER '{clusterName}' clause to the mutation. This ensures that checksum updates are propagated across all nodes in the ClickHouse cluster.

The diagram shows how cluster settings are integrated into the SQL generation process.
Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:47-50, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-84

Data Model Requirements

The DATABASECHANGELOG table must include specific columns for this feature to function. The checksum itself is stored in the MD5SUM column.

Column	Type	Nullable	Description
ID	String	No	Unique identifier for the changeset.
AUTHOR	String	No	Author of the changeset.
FILENAME	String	No	Path to the changelog file.
MD5SUM	String	Yes	The calculated checksum of the changeset.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:59-72

Summary

Updating ChangeSet checksums in the ClickHouse extension is achieved through synchronized ALTER TABLE mutations. By implementing UpdateChangeSetChecksumClickHouse, the extension ensures that Liquibase's internal state remains consistent even in clustered ClickHouse environments, using standard metadata (ID, Author, Filename) to precisely target records for checksum recalculation.