Database Tagging

Relevant source files

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

• src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.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/ParamsLoader.java
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java
• src/test/java/liquibase/ClickHouseTest.java

Database Tagging in the Liquibase ClickHouse extension provides a mechanism to mark a specific point in the database's change history. This is achieved by updating the TAG column in the DATABASECHANGELOG table for the most recently executed change set. Tags are essential for identifying stable versions of the schema and facilitating targeted rollbacks.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java, README.md:16

Architecture and Implementation

The tagging functionality is implemented through the TagDatabaseGeneratorClickhouse class, which extends the standard Liquibase TagDatabaseGenerator. It specifically targets the ClickHouseDatabase implementation and overrides the SQL generation logic to accommodate ClickHouse's mutation syntax.

Key Components

• TagDatabaseGeneratorClickhouse: The primary class responsible for generating the ALTER TABLE ... UPDATE SQL statement required to apply a tag in ClickHouse.
• DATABASECHANGELOG Table: The metadata table where tags are stored. It contains a TAG column defined as Nullable(String).
• ClusterConfig: Provides cluster-specific information (like cluster name) to ensure tags are applied across the entire cluster if configured.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java:36-47, src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:54

Data Flow for Tagging

The following diagram illustrates how a tagging request is transformed into a ClickHouse-specific SQL mutation.

The process identifies the most recent entry in the changelog based on DATEEXECUTED and ORDEREXECUTED and updates its TAG field.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java:51-93

SQL Generation Logic

Unlike standard SQL UPDATE statements, ClickHouse uses an ALTER TABLE ... UPDATE syntax for asynchronous mutations. The extension forces synchronous behavior for tagging to ensure the operation completes before subsequent tasks.

The Tagging Query

The generated SQL performs the following actions:

1. Identifies the DATABASECHANGELOG table name and escapes it.
2. Appends an ON CLUSTER clause if cluster settings are detected via ParamsLoader.
3. Sets the TAG value.
4. Uses a subquery to locate the record with the maximum DATEEXECUTED and ORDEREXECUTED.
5. Appends SETTINGS mutations_sync = 1 to wait for the mutation to finish.

ALTER TABLE `default`.DATABASECHANGELOG 
[ON CLUSTER 'cluster_name'] 
UPDATE TAG='my_tag' 
WHERE DATEEXECUTED=(SELECT DATEEXECUTED FROM `default`.DATABASECHANGELOG ORDER BY DATEEXECUTED DESC, ORDEREXECUTED DESC LIMIT 1) 
AND ORDEREXECUTED=(SELECT ORDEREXECUTED FROM `default`.DATABASECHANGELOG ORDER BY DATEEXECUTED DESC, ORDEREXECUTED DESC LIMIT 1) 
SETTINGS mutations_sync = 1

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java:51-93

Cluster Support

If the extension is configured for cluster mode via a liquibaseClickhouse.conf file, the tagging operation becomes cluster-aware. This ensures that the tag is consistent across all replicas in the ClickHouse cluster.

Feature	Cluster Mode Detail	Source
Clause Generation	ON CLUSTER '{clusterName}' added to ALTER statement	SqlGeneratorUtil.java:49-52
Property Loading	Parameters loaded from cluster config block	ParamsLoader.java:94-110
Synchronization	mutations_sync = 1 ensures consistency across nodes	TagDatabaseGeneratorClickhouse.java:91

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java

Related Changelog Schema

The tagging feature relies on the specific structure of the DATABASECHANGELOG table created for ClickHouse.

Integration Testing

The tagging functionality is verified through integration tests that utilize Testcontainers to spin up a real ClickHouse instance.

  @Test
  void canTagDatabase() {
    runLiquibase(
        "changelog.xml",
        (liquibase, database) -> {
          liquibase.update("");
          liquibase.tag("testTag");
        });
  }

Sources: src/test/java/liquibase/ClickHouseTest.java:70-77

Summary

Database Tagging in ClickHouse is a specialized mutation process. By leveraging ALTER TABLE ... UPDATE with synchronous settings, the extension ensures that version markers are accurately applied to the latest changelog entries, even in complex clustered environments. This provides the necessary metadata for Liquibase to manage schema history and rollbacks effectively on the ClickHouse platform.