Configuration Loader (ParamsLoader)

Relevant source files

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

• 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
• README.md
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java

The Configuration Loader (ParamsLoader) is a core utility component within the Liquibase ClickHouse extension designed to handle environment-specific configurations for ClickHouse clusters. Its primary purpose is to detect and load parameters from external configuration files to determine if Liquibase should operate in a single-instance mode or a replicated cluster mode.

By default, the loader looks for a configuration file named liquibaseClickhouse.conf. When cluster settings are present and valid, the system adapts its SQL generation strategy to include ON CLUSTER clauses and uses replicated table engines (e.g., ReplicatedMergeTree) for internal Liquibase tables like the ChangeLog and Lock tables.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:92-120, README.md:27-38

Architecture and Data Flow

The ParamsLoader serves as a bridge between the filesystem (HOCON/Typesafe configuration files) and the SQL generators. It utilizes the com.typesafe.config library to parse properties and maps them into a ClusterConfig data object.

Configuration Loading Flow

The following diagram illustrates how ParamsLoader processes a configuration request and validates the resulting properties.

Key Components

Class	Responsibility
ParamsLoader	Static utility class that loads, validates, and caches cluster settings.
ClusterConfig	POJO storing clusterName, tableZooKeeperPathPrefix, and tableReplicaName.
SqlGeneratorUtil	Consumes ClusterConfig to append ON CLUSTER and ENGINE clauses to SQL.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:38-42, src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java:23-27, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:44-59

Configuration Parameters

The loader enforces a strict set of required properties. If any are missing or if unknown properties are detected, the loader reverts to single-instance mode to ensure system stability.

Required Properties

Property Name	Description	Example Value
clusterName	The name of the ClickHouse cluster for ON CLUSTER execution.	{cluster}
tableZooKeeperPathPrefix	The ZK path used when creating replicated tables.	/clickhouse/tables/{shard}/
tableReplicaName	The replica identifier for the Replicated engine.	{replica}

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:43-45, README.md:29-33

Validation Logic

The loader performs a two-step validation:

1. Unknown Property Check: Ensures no keys exist outside the valid set (clusterName, tableZooKeeperPathPrefix, tableReplicaName).
2. Completeness Check: Verifies that all three required properties are present.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:59-75

Usage in SQL Generation

The ParamsLoader is invoked by SQL generators to dynamically adjust table creation and maintenance statements. If ParamsLoader.getLiquibaseClickhouseProperties() returns a non-null object, the extension assumes a cluster environment.

SQL Engine Selection Logic

Implementation Example: Table Creation

In CreateDatabaseChangeLogTableClickHouse, the loader is used to fetch properties which are then passed to SqlGeneratorUtil to format the final DDL:

// From CreateDatabaseChangeLogTableClickHouse.java
ClusterConfig properties = ParamsLoader.getLiquibaseClickhouseProperties();
String createTableQuery = String.format(
    "CREATE TABLE IF NOT EXISTS `%s`.%s "
    + SqlGeneratorUtil.generateSqlOnClusterClause(properties)
    + "(...) "
    + SqlGeneratorUtil.generateSqlEngineClause(properties, tableName.toLowerCase(Locale.ROOT)),
    database.getDefaultSchemaName(),
    tableName);

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:53-75

Error Handling and Logging

ParamsLoader is designed to be fail-safe. If the configuration file is missing or corrupted, the system logs the event and continues in a "single-instance" mode.

• Missing Configuration: Logs an INFO message stating that cluster settings are not defined and lists the properties that would be required for cluster mode.
• Invalid Format: If properties are malformed, it logs a SEVERE error with a stack trace and defaults to single-instance mode.
• Caching: Once loaded (successfully or as null), the result is stored in a static variable liquibaseClickhouseProperties to avoid repeated filesystem I/O.

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:40, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:108-120

Summary

The ParamsLoader is the central mechanism for enabling ClickHouse cluster support in Liquibase. By abstracting the configuration retrieval and providing a structured ClusterConfig object, it allows the extension to remain flexible, supporting both standalone ClickHouse instances and complex replicated environments through a simple .conf file interface.