Changelog Formats
Relevant source files
The following files were used as context for generating this wiki page:
- src/test/resources/changelog.xml
- src/test/resources/empty-changelog.xml
- src/test/resources/test-script.sql
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogLockTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java
Changelog formats in the Liquibase ClickHouse extension define how database migrations and tracking metadata are structured and persisted within a ClickHouse environment. The project supports standard XML-based definitions that can reference external formatted SQL files, enabling both declarative and imperative migration styles.
These formats ensure that Liquibase can track which changes have been applied via the DATABASECHANGELOG table and manage concurrent execution through the DATABASECHANGELOGLOCK table, specifically tailored for ClickHouse's MergeTree engine family.
Sources: src/test/resources/changelog.xml, src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java:54-72
XML Changelog Structure
The primary entry point for migrations is the XML changelog. This format follows the standard Liquibase schema but is utilized by the extension to orchestrate ClickHouse-specific SQL generation. It can be empty for schema initialization or include references to other migration files.
XML Schema and Includes
The XML format uses the databaseChangeLog root element and can include external files such as formatted SQL scripts.
<?xml version="1.0" ?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.9.xsd">
<include file="test-script.sql"/>
</databaseChangeLog>
Sources: src/test/resources/changelog.xml:2-8, src/test/resources/empty-changelog.xml:2-6
Formatted SQL Changelog
The "Formatted SQL" format allows developers to write native ClickHouse SQL while retaining Liquibase metadata like changeSet IDs, authors, and rollback logic.
Structure of Formatted SQL
Each file must start with the --liquibase formatted sql marker. Individual units of work are delimited by --changeset comments, which include an identifier and an author.
| Component | Syntax | Description |
|---|---|---|
| Header | --liquibase formatted sql | Identifies the file as a Liquibase SQL changelog. |
| ChangeSet | --changeset author:id | Defines a unique block of migration logic. |
| Rollback | --rollback <SQL> | Defines the SQL required to undo the specific changeset. |
Sources: src/test/resources/test-script.sql:1-12
Execution Flow for SQL Changelogs
The following diagram illustrates how a formatted SQL changelog is processed into the ClickHouse database.
The flow shows the inclusion of SQL scripts into the main XML changelog and their subsequent execution as discrete changesets recorded in the tracking table.
Sources: src/test/resources/changelog.xml, src/test/resources/test-script.sql
Internal Tracking Formats
The extension defines specific ClickHouse table structures to track migration history and locks. These tables use ClickHouse-specific data types such as DateTime64 and UInt64.
DATABASECHANGELOG Table Schema
This table tracks the execution status of every changeset.
| Column | ClickHouse Type | Description |
|---|---|---|
| ID | String | Unique identifier from changeset |
| AUTHOR | String | Author of the changeset |
| FILENAME | String | Path to the changelog file |
| DATEEXECUTED | DateTime64 | Timestamp of execution |
| ORDEREXECUTED | UInt64 | Incremental order of execution |
| EXECTYPE | String | Execution status (e.g., EXECUTED) |
| MD5SUM | Nullable(String) | Checksum for change detection |
| TAG | Nullable(String) | Version tag for rollbacks |
DATABASECHANGELOGLOCK Table Schema
Used to prevent concurrent Liquibase instances from updating the same database.
| Column | ClickHouse Type | Description |
|---|---|---|
| ID | Int64 | Primary key (usually 1) |
| LOCKED | UInt8 | Boolean flag (0 or 1) |
| LOCKGRANTED | Nullable(DateTime64) | When the lock was acquired |
| LOCKEDBY | Nullable(String) | Identifier of the lock holder |
Engine and Storage Configuration
When generating these tables, the extension defaults to the MergeTree engine family. If cluster properties are detected via ParamsLoader, it switches to ReplicatedMergeTree.
This diagram represents the relationship between the SQL generation utilities and the database implementation used to format changelog tracking tables.
Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:48-55, src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:36-41
Summary
Changelog formats for the ClickHouse extension bridge standard Liquibase XML/SQL structures with the specific technical requirements of the ClickHouse database. By utilizing native types like DateTime64 and specific engines like MergeTree or ReplicatedMergeTree, the extension ensures that migration metadata is stored efficiently and reliably across both single-node and clustered ClickHouse deployments.