The liquibaseClickhouse.conf File

Relevant source files

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

• README.md
• src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java
• src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java
• src/test/java/liquibase/ParamsLoaderTest.java
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java

The liquibaseClickhouse.conf file is the primary configuration mechanism for enabling and managing cluster-replicated mode within the Liquibase ClickHouse extension. When this file is present in the application's resources, the extension shifts from single-instance mode to cluster mode, ensuring that Liquibase's internal tracking tables (like DATABASECHANGELOG and DATABASECHANGELOGLOCK) are created as replicated tables across a ClickHouse cluster.

Sources: README.md:20-25, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-85

Configuration Structure

The file uses the HOCON (Human-Optimized Config Object Notation) format, processed via the TypeSafe Config library. All cluster-related settings must be nested within a top-level cluster block.

Required Properties

For a configuration to be considered valid, it must contain exactly three specific properties. If any are missing or if unknown properties are included, the system logs a severe error and reverts to single-instance mode.

Property	Description
clusterName	The name of the ClickHouse cluster where tables should be created.
tableZooKeeperPathPrefix	The Zookeeper path prefix used for replicated table synchronization.
tableReplicaName	The identifier for the specific replica.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:32-34, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:55-58, src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java:23-45

Example Configuration

cluster {
    clusterName="{cluster}"
    tableZooKeeperPathPrefix="/clickhouse/tables/{shard}/{database}/"
    tableReplicaName="{replica}"
}

Sources: README.md:21-25

Loading Logic and Data Flow

The ParamsLoader class is responsible for locating and parsing the configuration. It attempts to load liquibaseClickhouse.conf by default using ConfigFactory.load().

Loading Process Flow

The following diagram illustrates how the extension decides between single-instance and cluster-replicated mode:

The system utilizes a singleton-like pattern where the liquibaseClickhouseProperties are cached after the first successful or unsuccessful load attempt to avoid repeated disk I/O.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:73-100

Impact on SQL Generation

When liquibaseClickhouse.conf is successfully loaded, it populates a ClusterConfig object that influences several SQL generators. Specifically, it modifies how tables are defined and how mutations are executed.

ON CLUSTER Clause

If a ClusterConfig exists, the extension appends an ON CLUSTER '{clusterName}' clause to DDL and DML statements, such as table creation, updates to checksums, and lock management.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:45-48, src/main/java/liquibase/ext/clickhouse/sqlgenerator/LockDatabaseChangeLogClickHouse.java:51-55

Replicated Table Engines

The presence of this configuration changes the default ENGINE from MergeTree() to ReplicatedMergeTree(). The engine parameters are dynamically constructed using the Zookeeper path and replica name defined in the config file.

Config State	Generated Engine Clause
No Config	ENGINE MergeTree() ORDER BY ID
Config Present	ENGINE ReplicatedMergeTree('{path}{tableName}', '{replica}') ORDER BY ID

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:50-57, src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:56-78

Summary

The liquibaseClickhouse.conf file is the toggle for enterprise-grade deployments of ClickHouse. By providing Zookeeper and cluster metadata, it ensures that Liquibase manages its own metadata tables with the same high-availability and replication standards as the application data they manage. Without this file, the extension operates safely but only on a per-node basis.

Sources: README.md:20-30, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-95