We Open-Sourced ClickMigrate

A few days ago, we open sourced ClickMigrate, a migration framework built specifically for ClickHouse. Since then, we've been happy to see people trying it out, giving feedback, and contributing ideas for future improvements.

If you haven't seen it yet, you can find the project on GitHub: github.com/QueueForge/ClickMigrate.

Why We Built ClickMigrate

Managing database schema changes should not require a complicated workflow. As projects grow, it becomes increasingly important to know which changes have already been applied and whether every environment is in the same state.

While working with ClickHouse, we found ourselves relying on manually executed SQL files and small helper scripts. They worked, but they also made deployments more difficult than they needed to be. We wanted a simple migration workflow that fit naturally into Python projects without introducing another migration language.

That idea eventually became ClickMigrate.

Keeping It Simple

Every migration is just a SQL file. Files are executed in lexicographical order, recorded in a migration history table, and never executed twice.

ClickMigrate also stores a SHA-256 checksum for every applied migration. During validation, those checksums are compared against the current migration files, making it easy to detect changes to previously applied migrations.

Configuration is intentionally straightforward, with support for pyproject.toml, JSON, YAML, and environment variables.

Looking Ahead

The first release focuses on the core migration workflow, but there are already several improvements and features we want to explore. As always, we'll continue to keep the project small, predictable, and easy to understand.

We'd also like to thank everyone who has already reported bugs, opened issues, or suggested improvements during the first few days after the release.

One More Thing

During development, we came across a few small security issues while testing different parts of the project and its surrounding tooling. None of them were severe, but they were interesting enough that we documented the process and the fixes.

We'll publish a full write-up in the next Security Monday, where we'll walk through what we found, how the issues could be triggered, and what we changed to address them.

See you then,
The QueueForge Team