Version History and Changelog
Relevant source files
The following files were used as context for generating this wiki page:
- README.md
- pom.xml
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/CreateDatabaseChangeLogTableClickHouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/UpdateChangeSetChecksumClickHouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/TagDatabaseGeneratorClickhouse.java
- src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java
- src/test/resources/test-script.sql
The "Version History and Changelog" system in the Liquibase ClickHouse extension manages the recording, tracking, and auditing of database schema changes. It ensures that every modification—defined as a "changeset"—is logged in a persistent tracking table, allowing the system to determine which updates have been applied and which are pending.
This system is built upon the DATABASECHANGELOG table structure, adapted specifically for ClickHouse's requirements, such as the MergeTree engine family and its unique ALTER TABLE ... UPDATE syntax for handling record modifications and checksum updates.
Sources: CreateDatabaseChangeLogTableClickHouse.java, README.md:12-14
Changelog Table Structure
The core of the version history is the DATABASECHANGELOG table. In ClickHouse, this table is created using a specific schema that supports Liquibase's standard auditing fields while utilizing ClickHouse-native data types like DateTime64 and UInt64.
Table Schema Definition
The table stores the identity of each changeset (ID, Author, Filename) along with execution metadata.
| Field | Type | Description |
|---|---|---|
| ID | String | Unique identifier for the changeset |
| AUTHOR | String | The creator of the changeset |
| FILENAME | String | The source file containing the changeset |
| DATEEXECUTED | DateTime64 | Timestamp of execution |
| ORDEREXECUTED | UInt64 | Sequence order of execution |
| EXECTYPE | String | The type of execution (e.g., RAN) |
| MD5SUM | Nullable(String) | Checksum of the changeset content |
| TAG | Nullable(String) | Optional version tag |
| DEPLOYMENT_ID | Nullable(String) | ID grouping changes in a single run |
Sources: CreateDatabaseChangeLogTableClickHouse.java:55-68
Database Engine Logic
The tracking table is created using different engines based on the configuration. If cluster mode is active, it uses ReplicatedMergeTree; otherwise, it defaults to MergeTree.
Changelog Management Operations
The extension implements several generators to handle the lifecycle of version history entries, including recording new runs, updating checksums, and removing entries during rollbacks.
Checksum Updates
When a changeset is modified in the source file, Liquibase updates the stored checksum. In ClickHouse, this is performed via an ALTER TABLE ... UPDATE statement with mutations_sync = 1 to ensure the update is processed synchronously.
Sources: UpdateChangeSetChecksumClickHouse.java:56-66
Database Tagging
Tagging allows developers to mark a specific point in the version history. The TagDatabaseGeneratorClickhouse identifies the most recently executed changeset (ordered by DATEEXECUTED and ORDEREXECUTED) and updates its TAG column.
History Removal (Rollback)
During a rollback operation, the entry for the reverted changeset must be removed from the history. This is achieved through a DELETE mutation on the changelog table.
Sources: RemoveChangeSetRanStatusClickHouse.java:57-67
Change Formatting
Changesets are defined in SQL files using the Liquibase formatted SQL syntax. This allows for clear versioning and rollback definitions directly within the script.
--liquibase formatted sql
--changeset test:1
CREATE TABLE test (
ID UInt8,
DESC String
) ENGINE MergeTree() ORDER BY ID;
--rollback DROP table test
Sources: test-script.sql:1-9
Project Evolution and Versioning
The project tracks its own compatibility with Liquibase and ClickHouse versions through its build configuration and documentation.
| Project Version | Liquibase Version | Key Changes |
|---|---|---|
| 0.6.0 | 4.3.5 | Adaptation for Liquibase v4.3.5 |
| 0.7.0 | 4.6.1 | Support for cluster replication |
| 0.7.5-SNAPSHOT | 4.15.0 | Current development baseline |
Sources: README.md:31-34, pom.xml:14, 49
The version history system ensures that the ClickHouse database remains in a deterministic state by rigorously tracking every modification through its specialized changelog implementation. This mechanism supports both single-node and replicated cluster environments, maintaining consistency across the infrastructure.