Integration Testing Strategy

Relevant source files

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

• src/test/java/liquibase/ClickHouseTest.java
• pom.xml
• src/test/java/liquibase/ParamsLoaderTest.java
• src/test/resources/changelog.xml
• src/test/resources/test-script.sql
• src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java

Introduction

The integration testing strategy for the Liquibase ClickHouse extension focuses on verifying the end-to-end compatibility between Liquibase core logic and the ClickHouse database. The primary goal is to ensure that database migrations, schema initializations, and cluster-specific configurations function correctly within a real ClickHouse environment.

This strategy utilizes containerized instances of ClickHouse to provide a consistent, isolated environment for running tests. It covers essential Liquibase operations including updates, rollbacks, tagging, and lock management, as well as the specialized configuration loading for cluster-aware deployments.

Sources: src/test/java/liquibase/ClickHouseTest.java, README.md:1-10

Testing Infrastructure and Dependencies

The project leverages a modern testing stack integrated into the Maven build lifecycle. The infrastructure relies on JUnit 5 for test orchestration and Testcontainers for database lifecycle management.

Key Dependencies

The following table summarizes the core dependencies used for integration testing as defined in the project configuration:

Dependency	Version	Scope	Purpose
junit-jupiter	5.4.0	test	Test runner and assertions
testcontainers clickhouse	1.17.3	test	Provides managed ClickHouse Docker containers
clickhouse-jdbc	0.5.0	compile	JDBC driver for database connectivity
liquibase-core	4.15.0	provided	Core Liquibase framework

Sources: pom.xml:193-219

Container Orchestration

The testing suite uses the ClickHouseContainer class to spin up a specific version of the database. For the current suite, the image clickhouse/clickhouse-server:22.3.8.39 is utilized.

The diagram shows how JUnit utilizes Testcontainers to manage the lifecycle of a ClickHouse Docker container, which then provides the JDBC connection for the tests.
Sources: src/test/java/liquibase/ClickHouseTest.java:38-41

Test Execution Workflow

Integration tests follow a standardized lifecycle to ensure clean state and proper resource management. The core logic is encapsulated in a runLiquibase helper method.

The runLiquibase Pattern

Every integration test follows these steps:

1. Container Connection: Create a JDBC connection to the active ClickHouseContainer.
2. Implementation Discovery: Use DatabaseFactory to identify the ClickHouseDatabase implementation.
3. Liquibase Initialization: Instantiate a Liquibase object with a specific changelog (e.g., changelog.xml or empty-changelog.xml).
4. Action Execution: Execute a functional interface callback (liquibaseAction) containing the specific Liquibase command (e.g., update, rollback, tag).

Sources: src/test/java/liquibase/ClickHouseTest.java:101-118

Sequence of Operation

This sequence diagram illustrates the flow from connection establishment through the execution of a Liquibase action against the containerized database.
Sources: src/test/java/liquibase/ClickHouseTest.java:108-115

Functional Test Coverage

The integration suite covers several critical Liquibase features modified or supported by the extension.

Core Operations

• Schema Initialization: Tests liquibase.update("") with empty-changelog.xml to verify table creation for DATABASECHANGELOG and DATABASECHANGELOGLOCK.
• Successive Updates: Verifies that running update twice with changelog.xml handles already-applied changesets correctly.
• Rollback: Executes a rollback to a specific count (e.g., 2 changesets) to verify the extension's ability to undo changes.
• Tagging: Verifies the tag command, which involves updating the TAG column in the changelog table using ClickHouse-specific ALTER TABLE ... UPDATE syntax.
• Lock Management: Tests listLocks and forceReleaseLocks to ensure the extension handles ClickHouse's mutation-based updates for locking.

Sources: src/test/java/liquibase/ClickHouseTest.java:43-99, src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java:60-84

Data and Scripts

Tests use a formatted SQL changelog containing ClickHouse-specific engines:
Sources: src/test/resources/test-script.sql:3-15

Configuration and Cluster Testing

Beyond database operations, the testing strategy includes validation of the parameter loading system used for ClickHouse clusters.

Parameter Validation

The ParamsLoaderTest verifies the ability to parse .conf files (using Typesafe Config). It ensures that:

• Valid configurations (e.g., testLiquibaseClickhouse.conf) correctly populate the ClusterConfig object.
• Broken configurations (e.g., testLiquibaseClickhouseBroken.conf with misspelled keys) result in a null configuration, triggering single-instance mode.

Sources: src/test/java/liquibase/ParamsLoaderTest.java:29-44, src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:94-118

Cluster Configuration Structure

Property	Expected Key in .conf	Usage
Cluster Name	clusterName	Used in ON CLUSTER clauses
ZooKeeper Path	tableZooKeeperPathPrefix	Used in ReplicatedMergeTree engine paths
Replica Name	tableReplicaName	Used in ReplicatedMergeTree engine parameters

Sources: src/main/java/liquibase/ext/clickhouse/params/ParamsLoader.java:39-40, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:49-62

Summary

The Integration Testing Strategy ensures the Liquibase ClickHouse extension remains robust by combining containerized database testing with rigorous configuration validation. By utilizing Testcontainers, the project guarantees that all Liquibase commands—ranging from basic updates to complex cluster-aware schema changes—are verified against an actual ClickHouse instance before release.

Sources: src/test/java/liquibase/ClickHouseTest.java:34-41, README.md:20-35