ClickHouse does not ship a built-in migration tool. Teams running production deployments wire ClickHouse into the same migration pipeline as their other databases. Several mature tools support ClickHouse natively or through community plugins. This guide compares the main options so you can pick one that matches your stack.
Atlas
Atlas provides native ClickHouse support, including diff-based migrations from declarative HCL or SQL schema definitions. Atlas computes the DDL needed to converge the live database to the desired state and applies it as versioned migrations.
Strengths: native support, declarative model, integrates with Terraform-style workflows.
Best for: teams that want declarative schema-as-code and are comfortable with a Go-based CLI.
golang-migrate
golang-migrate/migrate is a widely used Go-based migration tool with a stable ClickHouse driver. Migrations are pairs of forward/reverse SQL files (001_init.up.sql / 001_init.down.sql) tracked by a schema_migrations table.
migrate -database 'clickhouse://localhost:9000?username=default&database=mydb' \
-path ./migrations up
Strengths: minimal, scriptable, easy to embed in CI/CD.
Best for: teams already standardized on golang-migrate for other databases.
Liquibase
Liquibase supports ClickHouse through a community-maintained extension. Migrations are defined in XML, YAML, JSON, or SQL changelogs. The extension translates Liquibase's database-agnostic operations into ClickHouse DDL.
Strengths: enterprise tooling, change tracking, integration with Java build systems.
Best for: organizations standardized on Liquibase for Oracle, PostgreSQL, or MySQL who want one tool across all databases.
Flyway
Flyway now offers community-supported ClickHouse integration through a dedicated plugin in their community database support repository. Migrations are SQL files with a V<version>__<name>.sql naming convention, applied in order.
Strengths: simple SQL-first model, mature CLI, Java agent for embedded use.
Best for: teams already using Flyway for other databases and wanting consistency.
Alembic
Alembic is the migration tool tied to SQLAlchemy. ClickHouse support comes from the clickhouse-sqlalchemy driver. Migrations are Python files generated from model changes.
Strengths: Python-native, model-driven autogeneration, useful for Django/SQLAlchemy stacks.
Best for: Python applications that already use SQLAlchemy and want migrations close to the ORM.
dbmate
dbmate is a database-agnostic CLI written in Go. ClickHouse support is built in. Migrations are timestamp-prefixed SQL files with -- migrate:up and -- migrate:down sections.
Strengths: minimal dependencies, single binary, works across many databases.
Best for: polyglot environments where the same tool needs to handle ClickHouse alongside PostgreSQL or MySQL.
Houseplant
Houseplant is a Python-based CLI migration tool released in late 2024 by June. It targets ClickHouse specifically and uses YAML-formatted migration files with automatic schema tracking.
Strengths: ClickHouse-first design, YAML migrations, ActiveRecord-style ergonomics.
Best for: teams that want a ClickHouse-only migration tool with readable, declarative migration files.
ClickSuite
ClickSuite by Gamebeast is a TypeScript CLI focused on managing ClickHouse migrations with environment-specific configurations. It supports per-environment overrides, useful when staging and production differ in cluster topology.
Strengths: environment-aware config, ClickHouse-specific features, TypeScript stack.
Best for: teams managing multiple ClickHouse environments with different cluster definitions.
Bytebase
Bytebase is a web-based database change management platform with ClickHouse support. It adds review workflows, change history, and approval gates.
Strengths: web UI, review workflows, multi-database support, audit log.
Best for: organizations that need approval workflows on schema changes across many databases.
Comparison at a Glance
| Tool | Language | ClickHouse Support | Strength |
|---|---|---|---|
| Atlas | Go | Native | Declarative schema |
| golang-migrate | Go | Native driver | Minimal, scriptable |
| Liquibase | Java | Community plugin | Enterprise, multi-DB |
| Flyway | Java | Community plugin | SQL-first, mature |
| Alembic | Python | Via SQLAlchemy | Python/ORM stacks |
| dbmate | Go | Native | Polyglot CLI |
| Houseplant | Python | Native | YAML migrations |
| ClickSuite | TypeScript | Native | Multi-environment |
| Bytebase | Go | Native | Review workflows |
Picking a Tool
Match the migration tool to the rest of your stack rather than to ClickHouse specifically. If your other databases use Flyway, use the Flyway plugin. If you are a Go shop, golang-migrate or dbmate are the lowest-friction choices. If you want declarative schema as code, Atlas is the strongest option.
The two anti-patterns to avoid are:
- Running schema changes manually in production. ClickHouse will not stop you, but you lose audit trail and ability to reproduce environments.
- Using two different tools for the same database. Pick one and route every change through it.
Common Pitfalls
- Forgetting
ON CLUSTERclauses in migrations. The migration succeeds on one node and silently skips the rest. - Not testing migrations against the cluster topology. A single-node test passes; replication or Distributed failures only show in production.
- Storing the
schema_migrationstable on only one node when running on a cluster. Different nodes can end up at different versions. - Mixing declarative tools (Atlas) and imperative tools (golang-migrate) on the same database.
Frequently Asked Questions
Q: Does ClickHouse have an official migration tool? A: No. The ecosystem relies on third-party tools, several of which have native ClickHouse drivers.
Q: Which tool is most widely used? A: golang-migrate and Atlas have the largest production footprint for ClickHouse-only projects. Liquibase and Flyway dominate where ClickHouse joins an existing multi-database stack.
Q: Do migrations need to be cluster-aware?
A: Yes, when running on a ClickHouse Keeper / ZooKeeper-backed cluster. Use ON CLUSTER clauses, and pick a tool that lets you parameterize the cluster name per environment.
Q: How do I handle rollbacks in ClickHouse? A: ClickHouse does not support transactional DDL, so rollbacks are best-effort. Write reversible migrations where possible, and rely on backups for the cases that are not reversible (column drops, table renames).
Q: Can I use dbt for schema migrations? A: dbt manages models and is not a migration tool in the same sense. Use dbt for analytical models and a dedicated migration tool for DDL changes.
