Test Scripts and XML Resources
Relevant source files
The following files were used as context for generating this wiki page:
The "Test Scripts and XML Resources" module provides the foundational data structures and SQL definitions required to validate the Liquibase ClickHouse extension. These resources include Liquibase changelogs (XML), raw SQL scripts, and configuration files that simulate various database states and migration scenarios.
The primary purpose of these resources is to support integration testing via Testcontainers, ensuring that ClickHouse-specific SQL generation—such as ENGINE clauses and ON CLUSTER statements—functions correctly across different operations like updates, rollbacks, and tagging.
Resource Architecture and Flow
The test suite utilizes a combination of XML changelogs and external SQL scripts to define database migrations. The ClickHouseTest class orchestrates these resources by initializing a ClickHouseContainer and applying the defined changesets.
The following diagram illustrates the relationship between the test resources and the execution flow:
The diagram shows how the test runner selects different resource types (XML, SQL, Conf) to feed into the Liquibase engine for execution against a ClickHouse instance.
Sources: src/test/java/liquibase/ClickHouseTest.java:101-114, src/test/resources/changelog.xml:7
XML Changelog Structures
The project utilizes standard Liquibase XML formats to define the scope of migrations. These files serve as the entry point for the Liquibase engine during test execution.
Changelog Definitions
| File Name | Purpose | Key Components |
|---|---|---|
changelog.xml | Primary test entry point. | Includes test-script.sql. |
empty-changelog.xml | Validates schema initialization. | Empty <databaseChangeLog> tag. |
Sources: src/test/resources/changelog.xml:1-8, src/test/resources/empty-changelog.xml:1-6
Execution Logic in Tests
The ClickHouseTest class uses these XML files to perform various operations. For instance, empty-changelog.xml is used to verify that Liquibase can successfully create internal metadata tables (DATABASECHANGELOG and DATABASECHANGELOGLOCK) without any user-defined changes.
Sources: src/test/java/liquibase/ClickHouseTest.java:45-47
Formatted SQL Scripts
The project uses "Liquibase Formatted SQL" to define specific database objects and data manipulations. This format allows for the inclusion of metadata and rollback logic directly within SQL comments.
Example: test-script.sql
The test-script.sql file defines a table named test using ClickHouse-specific syntax, such as the MergeTree engine.
--liquibase formatted sql
--changeset test:1
CREATE TABLE test (
ID UInt8,
DESC String
) ENGINE MergeTree() ORDER BY ID;
--rollback DROP table test
--changeset test:2
INSERT INTO test VALUES (1, 'foo');
--rollback ALTER TABLE test DELETE WHERE ID IN (1,2,3)
Sources: src/test/resources/test-script.sql:1-13
Configuration Resources
Test resources also include .conf files used to validate the ParamsLoader and cluster configuration logic. These files follow the HOCON/Typesafe Config format.
Cluster Configuration Parameters
The file testLiquibaseClickhouse.conf provides a mock environment for testing replicated and clustered operations.
| Parameter | Value in Test | Description |
|---|---|---|
clusterName | "Cluster1" | Name of the ClickHouse cluster. |
tableZooKeeperPathPrefix | "Path1" | ZK path for replicated tables. |
tableReplicaName | "Replica1" | Unique name for the replica. |
Sources: src/test/resources/testLiquibaseClickhouse.conf:2-6
Integration with Database Implementation
The resources are interpreted based on the ClickHouseDatabase implementation, which defines specific constants and functions for the ClickHouse environment.
The class diagram shows how the test suite relies on the ClickHouseDatabase metadata to correctly identify the target environment.
Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:31-88, src/test/java/liquibase/ClickHouseTest.java:39-42
Summary
The "Test Scripts and XML Resources" provide the necessary configuration and data definitions to validate the extension's behavior. By combining standard Liquibase XML changelogs with ClickHouse-specific SQL scripts and HOCON configuration files, the system ensures that complex operations like clustered table creation and mutations-based updates are handled correctly.