Installation and Setup
Relevant source files
The following files were used as context for generating this wiki page:
This document provides technical instructions for installing and configuring the Liquibase ClickHouse extension. This extension allows Liquibase to manage database migrations for ClickHouse, supporting both single-instance and clustered/replicated environments.
The extension integrates with Liquibase via the standard JDBC mechanism, utilizing the clickhouse-jdbc driver to communicate with the database. It provides custom SQL generators to handle ClickHouse-specific syntax, such as MergeTree engines and ON CLUSTER clauses.
Sources: README.md:1-5, pom.xml:145-154, src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:37-45
Dependency Management
To include the extension in a Java project, you must add the dependency to your build configuration. The project is built using Maven and targets Java 11.
Maven Configuration
Add the following dependency to your pom.xml:
<dependency>
<groupId>com.mediarithmics</groupId>
<artifactId>liquibase-clickhouse</artifactId>
<version>0.7.5-arenadata-SNAPSHOT</version>
</dependency>
The extension requires liquibase-core (version 4.15.0) and the clickhouse-jdbc driver (version 0.5.0).
Sources: README.md:10-16, pom.xml:11-13, pom.xml:45-46, pom.xml:145-154
Environment Configuration
The extension supports two primary modes of operation: Single-instance mode and Cluster Replicated mode.
Single-Instance Mode
This is the default mode. Tables are created using the MergeTree() engine without cluster-specific clauses. No additional configuration file is required.
Cluster Replicated Mode
To enable cluster support, you must create a configuration file named liquibaseClickhouse.conf in your project's resources directory. This file uses the HOCON (Typesafe Config) format.
cluster {
clusterName="{cluster}"
tableZooKeeperPathPrefix="/clickhouse/tables/{shard}/{database}/"
tableReplicaName="{replica}"
}
When this configuration is present, the extension:
- Appends the
ON CLUSTER '{clusterName}'clause to DDL statements. - Uses the
ReplicatedMergeTreeengine for Liquibase metadata tables. - Facilitates synchronization across the cluster using the
mutations_sync = 1setting forALTERandDELETEoperations.
Sources: README.md:18-28, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:94-114, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:49-61
Configuration Parameters
The following parameters are supported within the cluster block of liquibaseClickhouse.conf:
| 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 Replicated tables. |
tableReplicaName | String | The macro or name used to identify the replica (e.g., {replica}). |
Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:42-43, src/main/java/liquibase/ext/clickhouse/params/ClusterConfig.java:24-30
Internal Logic: Parameter Loading
The ParamsLoader class is responsible for detecting and parsing the cluster configuration.
The diagram shows how the extension decides between single-instance and cluster mode based on the presence and validity of the configuration file.
Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:82-119
Connection Setup
The extension identifies the database via the JDBC URL and the driver class.
- Default Port: 8123
- Driver Class:
com.clickhouse.jdbc.ClickHouseDriver - URL Prefix:
jdbc:clickhouse
Database Implementation Logic
The ClickHouseDatabase class provides the implementation for Liquibase to interact with ClickHouse. It disables certain standard SQL features that are not applicable to ClickHouse.
| Feature | Supported | Notes |
|---|---|---|
| Sequences | No | ClickHouse does not support sequences. |
| DDL in Transaction | No | DDL statements in ClickHouse are not transactional. |
| Tablespaces | No | Not supported by ClickHouse. |
| Deferrable Columns | No | Not supported by ClickHouse. |
Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:37-97
Verification and Testing
You can verify the setup by running a programmatic Liquibase update. For testing, the project utilizes Testcontainers with the clickhouse/clickhouse-server image.
// Example of manual initialization in a Java test
ClickHouseContainer clickHouseContainer = new ClickHouseContainer("clickhouse/clickhouse-server:22.3.8.39");
clickHouseContainer.start();
Connection connection = clickHouseContainer.createConnection("");
JdbcConnection jdbcConnection = new JdbcConnection(connection);
Database database = DatabaseFactory.getInstance().findCorrectDatabaseImplementation(jdbcConnection);
Liquibase liquibase = new Liquibase("changelog.xml", new ClassLoaderResourceAccessor(), database);
liquibase.update("");
Sources: src/test/java/liquibase/ClickHouseTest.java:41-45, src/test/java/liquibase/ClickHouseTest.java:101-112
Summary
Installation requires adding the Maven dependency and ensuring the clickhouse-jdbc driver is available. For cluster environments, the liquibaseClickhouse.conf file is essential to trigger replicated table engines and ON CLUSTER execution. Once configured, Liquibase treats ClickHouse as a standard database destination, while the extension handles the translation of metadata management into ClickHouse-compatible SQL.