Supported Operations Overview
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java
- src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java
- src/test/java/liquibase/ClickHouseTest.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java
Introduction
The Liquibase ClickHouse extension provides a specialized implementation for managing database schema migrations on ClickHouse. It bridges the gap between Liquibase's standard operational model and ClickHouse's unique architectural requirements, such as its specific SQL dialect and cluster replication capabilities. The core purpose of this extension is to enable reliable schema versioning, locking, and synchronization across both standalone ClickHouse instances and distributed clusters.
Supported operations include core Liquibase lifecycle actions such as update, rollback (via provided SQL scripts), and database tagging. The extension handles the creation and management of internal Liquibase metadata tables—specifically DATABASECHANGELOG and DATABASECHANGELOGLOCK—using ClickHouse-specific engines like MergeTree or ReplicatedMergeTree depending on the configuration.
Sources: README.md:6, src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java
Core Lifecycle Operations
The extension supports the primary Liquibase commands required for automated migration pipelines. These operations are validated through integration tests that ensure compatibility with ClickHouse-specific syntax and transactional limitations.
Supported Command Summary
| Operation | Description | Implementation Detail |
|---|---|---|
| Update | Executes pending changesets against the database. | Uses ALTER TABLE ... UPDATE or INSERT based on metadata requirements. |
| Rollback | Reverts changes using a provided SQL script. | Requires manual rollback SQL in the formatted SQL changelog. |
| Tag | Marks the current state of the database with a version label. | Updates the latest entry in the changelog table. |
| Sync | Marks all changesets as ran without executing them. | Population of the metadata table. |
| Lock Management | Prevents concurrent Liquibase executions. | Custom implementation for DATABASECHANGELOGLOCK. |
Sources: README.md:6, src/test/java/liquibase/ClickHouseTest.java:44-93
The Update & Rollback Flow
The following sequence diagram illustrates the typical flow of an update operation, including how the extension handles the metadata lifecycle for ClickHouse.
Cluster & Replication Operations
A critical feature of the extension is its ability to operate in "Cluster Mode." When activated via the liquibaseClickhouse.conf configuration, the extension modifies its SQL generation logic to include ON CLUSTER clauses and utilizes replicated engines for internal metadata tables.
Cluster Configuration Parameters
The cluster behavior is driven by the ClusterConfig class, which is populated by the ParamsLoader.
| Parameter | Source Key | Description |
|---|---|---|
| Cluster Name | clusterName | The name of the ClickHouse cluster for the ON CLUSTER clause. |
| ZooKeeper Path | tableZooKeeperPathPrefix | The ZK path used for ReplicatedMergeTree engines. |
| Replica Name | tableReplicaName | The identifier for the specific replica. |
Sources: src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java:23-30, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-108
Engine Logic Flow
The extension dynamically selects the storage engine for metadata tables based on whether cluster properties are detected.
Metadata Management Operations
The extension overrides standard Liquibase SQL generators to ensure compatibility with ClickHouse's mutation system (which uses ALTER TABLE ... UPDATE/DELETE instead of standard UPDATE/DELETE).
SQL Mutation Handling
Because ClickHouse treats updates as asynchronous mutations by default, the extension explicitly sets mutations_sync = 1 in many operations to ensure that Liquibase waits for the metadata update to complete before proceeding to the next step.
- Tagging: Updates the
TAGcolumn whereDATEEXECUTEDandORDEREXECUTEDmatch the latest entry. - Checksum Updates: Updates the
MD5SUMfor a specific changeset after execution. - Ran Status Removal: Uses
ALTER TABLE ... DELETEto remove a changeset record during rollback or status changes.
Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java:55-80, src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java:52-59, src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java:52-59
Database Specific Constraints
The ClickHouseDatabase class defines the operational boundaries of the database implementation. Several standard Liquibase features are explicitly disabled due to ClickHouse's architecture:
- Transactions:
supportsDDLInTransaction()returnsfalse, as ClickHouse does not support multi-statement DDL transactions. - Sequences:
supportsSequences()returnsfalse. - Tablespaces:
supportsTablespaces()returnsfalse. - Schema Discovery: Uses
SELECT currentDatabase()to identify the connection schema.
Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:75-101
Conclusion
The Liquibase ClickHouse extension provides a robust suite of operations tailored for the ClickHouse ecosystem. By redirecting standard Liquibase metadata management through ClickHouse's mutation and replication engines, it allows developers to manage complex distributed schemas with the same workflow used for traditional RDBMS. Key to its operation is the mutations_sync setting, ensuring that the sequential nature of Liquibase migrations is preserved despite ClickHouse's eventual consistency models.