Cluster Mode Overview
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.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/sqlgenerator/CreateDatabaseChangeLogLockTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/LockDatabaseChangeLogClickHouse.java
Cluster Mode is a specialized execution state for the Liquibase ClickHouse extension that enables database schema management across a distributed ClickHouse cluster. Introduced in version 0.7.0, this mode ensures that Liquibase's internal metadata tables (ChangeLog and ChangeLogLock) are created as replicated tables and that schema updates are propagated across all nodes in the cluster.
Sources: README.md:27-29, ParamsLoader.java:94-96
Architecture and Configuration
Cluster mode is activated by the presence of a liquibaseClickhouse.conf file in the application resources. This configuration utilizes the Typesafe Config library to define cluster-specific parameters.
Configuration Parameters
The system requires three mandatory parameters to operate in cluster mode. If any are missing or incorrect, the extension reverts to single-instance mode.
| Parameter | Type | Description |
|---|---|---|
clusterName | String | The name of the ClickHouse cluster as defined in the server configuration. |
tableZooKeeperPathPrefix | String | The ZooKeeper path prefix used for ReplicatedMergeTree engines. |
tableReplicaName | String | The macro or name identifying the specific replica (e.g., {replica}). |
Sources: ClusterConfig.java:24-28, ParamsLoader.java:41-43, README.md:18-24
Configuration Loading Flow
The ParamsLoader class is responsible for detecting and validating the cluster configuration.
The diagram shows the logic used to determine if the extension should apply cluster-specific SQL clauses.
Sources: ParamsLoader.java:84-108
SQL Generation Logic
When Cluster Mode is active, the extension modifies the SQL generated for standard Liquibase operations by appending ON CLUSTER clauses and utilizing replicated table engines.
Replicated Table Engines
Instead of the standard MergeTree engine, Liquibase metadata tables are created using the ReplicatedMergeTree engine. This ensures that the DATABASECHANGELOG and DATABASECHANGELOGLOCK tables are synchronized via ZooKeeper.
- Standard Engine:
ENGINE MergeTree() ORDER BY ID - Cluster Engine:
ENGINE ReplicatedMergeTree('{zoo_path}', '{replica}') ORDER BY ID
Sources: SqlGeneratorUtil.java:45-51, CreateDatabaseChangeLogTableClickHouse.java:71-73
The ON CLUSTER Clause
The SqlGeneratorUtil class provides a helper method to append the ON CLUSTER '{clusterName}' clause to DDL and DML statements. This ensures the command is executed on every node participating in the cluster.
The sequence shows how SQL generators collaborate with utility classes to inject cluster-aware syntax.
Sources: SqlGeneratorUtil.java:40-43, CreateDatabaseChangeLogTableClickHouse.java:55-57
Impacted Operations
The following table summarizes how standard Liquibase operations are transformed in Cluster Mode:
| Operation | Cluster Modification | Technical Implementation |
|---|---|---|
| Table Creation | Adds ON CLUSTER and ReplicatedMergeTree | CreateDatabaseChangeLogTableClickHouse |
| Locking | Appends ON CLUSTER to ALTER TABLE ... UPDATE | LockDatabaseChangeLogClickHouse |
| Unlocking | Appends ON CLUSTER to ALTER TABLE ... UPDATE | UnlockDatabaseChangelogClickHouse |
| Checksum Update | Appends ON CLUSTER to ALTER TABLE ... UPDATE | UpdateChangeSetChecksumClickHouse |
| Tagging | Appends ON CLUSTER to ALTER TABLE ... UPDATE | TagDatabaseGeneratorClickhouse |
Sources: LockDatabaseChangeLogClickHouse.java:58-60, TagDatabaseGeneratorClickhouse.java:62-64, UpdateChangeSetChecksumClickHouse.java:57-59
Mutation Synchronization
For operations that modify existing data (like locking or updating checksums), the extension appends SETTINGS mutations_sync = 1. This ensures that the operation is synchronous and completed across the cluster before the next step in the Liquibase process proceeds.
Sources: LockDatabaseChangeLogClickHouse.java:65, UnlockDatabaseChangelogClickHouse.java:58, RemoveChangeSetRanStatusClickHouse.java:64
Summary
Cluster Mode allows Liquibase to function safely in distributed ClickHouse environments. By leveraging ReplicatedMergeTree and the ON CLUSTER clause, it maintains a consistent state of the changelog across all nodes. Users must ensure their own changesets also use these mechanisms to achieve full cluster-wide synchronization.
Sources: README.md:25-26