Rollback Mechanism

Relevant source files

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

• README.md
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java
• src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java
• src/test/java/liquibase/ClickHouseTest.java
• src/test/resources/test-script.sql
• src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java

The Rollback Mechanism in the Liquibase ClickHouse extension provides the ability to revert database changes to a previous state. This is achieved by executing user-defined SQL rollback scripts and subsequently updating the internal tracking tables to reflect that the specific change sets are no longer applied.

In the context of ClickHouse, rollbacks often involve specialized syntax such as ALTER TABLE ... DELETE or DROP statements to undo data insertions or schema modifications. The extension ensures that these operations are compatible with ClickHouse's asynchronous mutation engine while maintaining consistency within the Liquibase environment.

Sources: README.md:4, src/test/resources/test-script.sql:10-16

Architecture and Workflow

The rollback process involves two primary actions: executing the compensating SQL logic and removing the execution record from the DATABASECHANGELOG table.

Rollback Execution Flow

When a rollback is triggered (e.g., via liquibase.rollback()), the system identifies the change sets to be reverted based on the provided count or tag. For each change set, it executes the custom SQL provided in the --rollback comment of the Liquibase formatted SQL file.

The diagram shows the sequential steps from triggering a rollback to the final synchronization of database mutations.
Sources: src/test/java/liquibase/ClickHouseTest.java:54-61, src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java:46-59

Status Removal Logic

The RemoveChangeSetRanStatusClickHouse class is responsible for generating the SQL required to delete the record of a change set from the tracking table. Because ClickHouse handles deletions as mutations, the extension appends SETTINGS mutations_sync = 1 to ensure the deletion is processed synchronously before proceeding.

Sources: src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java:55-58

Implementation Details

Core Classes and Functions

The following components are central to the rollback implementation:

Component	Responsibility
ClickHouseDatabase	Defines database-specific properties, such as the lack of support for DDL transactions.
RemoveChangeSetRanStatusClickHouse	Generates the ALTER TABLE ... DELETE statement to clear change set history.
SqlGeneratorUtil	Provides utility methods to handle cluster clauses and engine configurations during SQL generation.
ClickHouseTest	Contains integration tests validating the canRollbackChangelog functionality.

Sources: src/main/java/liquibase/ext/clickhouse/database/ClickHouseDatabase.java:31, src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java:34, src/test/java/liquibase/ClickHouseTest.java:54

Rollback SQL Examples

Rollbacks are defined directly within the SQL changelog files. The extension supports various ClickHouse-specific undo operations:

--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)

Sources: src/test/resources/test-script.sql:5-16

Cluster Considerations

When operating in cluster mode, rollbacks must be propagated across all nodes. The extension utilizes the ON CLUSTER clause if configured in liquibaseClickhouse.conf.

1. Replication: Rollback commands affecting replicated tables are distributed via ZooKeeper.
2. Cluster Clause: The SqlGeneratorUtil injects the ON CLUSTER '{cluster}' snippet into the generated ALTER TABLE statements used during status removal.

The sequence diagram illustrates how the extension interacts with a ClickHouse cluster to ensure status removal is performed across all nodes.
Sources: README.md:12-21, src/main/java/liquibase/ext/clickhouse/sqlgenerator/SqlGeneratorUtil.java:43-46

Summary

The Rollback Mechanism in liquibase-clickhouse bridges the gap between Liquibase's standard version control and ClickHouse's unique architectural requirements. By leveraging synchronous mutations and cluster-aware SQL generation, it allows for reliable reversion of schema and data changes in both single-instance and distributed environments.

Sources: README.md:4, src/main/java/liquibase/ext/clickhouse/sqlgenerator/RemoveChangeSetRanStatusClickHouse.java:50-59