Introduction
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/params/ParamsLoader.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/lockservice/ClickHouseLockService.java
The liquibase-clickhouse project is a specialized Liquibase extension designed to provide schema migration support for the ClickHouse database. It enables developers to manage ClickHouse database changes using standard Liquibase workflows, including updates, rollbacks via SQL scripts, and database tagging. The extension supports both single-instance ClickHouse deployments and distributed cluster environments.
Sources: README.md:1-20, src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:27-40
Core Architecture and Database Integration
The extension integrates into the Liquibase ecosystem by providing a custom implementation of the Database interface. The ClickHouseDatabase class handles ClickHouse-specific behaviors, such as JDBC connection identification, default port settings (8123), and specific SQL syntax requirements.
Database Identification
The extension identifies ClickHouse connections via the JDBC URL prefix jdbc:clickhouse and the product name "ClickHouse". It disables standard SQL features not natively supported or applicable to ClickHouse's architecture, such as sequences and DDL transactions.
Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:47-113
Architecture Overview
The following diagram illustrates how the Liquibase core interacts with the ClickHouse extension to generate and execute SQL.
The Liquibase Core discovers the ClickHouse extension, which provides specialized database handling, locking mechanisms, and SQL generation tailored for ClickHouse.
Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java, src/main/java/liquibase/ext/clickhouse/lockservice/ClickHouseLockService.java
Cluster and Replication Support
A key feature of the extension is its ability to operate in a replicated cluster mode. This mode is activated by the presence of a configuration file named liquibaseClickhouse.conf. When cluster mode is active, the extension automatically appends ON CLUSTER clauses to DDL statements and utilizes the ReplicatedMergeTree engine for Liquibase's internal metadata tables.
Cluster Configuration Parameters
The cluster mode requires specific properties to be defined in the configuration file:
| Property | Description |
|---|---|
clusterName | The name of the ClickHouse cluster as defined in the server configuration. |
tableZooKeeperPathPrefix | The path prefix in ZooKeeper for replicated table metadata. |
tableReplicaName | The identifier for the specific replica. |
Sources: README.md:21-35, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:31-35
Engine Logic
The extension dynamically determines the table engine based on the environment:
- Single Instance: Uses
MergeTree(). - Cluster Mode: Uses
ReplicatedMergeTree()with paths derived from the configuration.
Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:49-56
Metadata Management
Liquibase maintains two internal tables to track changes: the Database ChangeLog and the ChangeLog Lock table. This extension provides custom generators to ensure these tables are compatible with ClickHouse's storage engines and syntax.
ChangeLog Table Schema
The DATABASECHANGELOG table is created using DateTime64 for execution timestamps and specific ClickHouse types for other fields.
| Column | ClickHouse Type |
|---|---|
| ID | String |
| AUTHOR | String |
| FILENAME | String |
| DATEEXECUTED | DateTime64 |
| ORDEREXECUTED | UInt64 |
| MD5SUM | Nullable(String) |
Locking Mechanism
The ClickHouseLockService manages database locks to prevent concurrent Liquibase executions. Because ClickHouse does not support standard row-level locking for updates in the same way as traditional RDBMS, the extension uses ALTER TABLE ... UPDATE and ALTER TABLE ... DELETE statements (mutations) with mutations_sync = 1 to ensure synchronous lock acquisition and release.
Conclusion
The liquibase-clickhouse extension bridges the gap between Liquibase's standard migration patterns and ClickHouse's unique OLAP architecture. By providing custom SQL generators, cluster-aware table engines, and specialized locking services, it allows for reliable database versioning across both standalone and distributed ClickHouse environments.
Sources: README.md:1-10, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:37-57