clickhouse-migrations

What it is and what it does

clickhouse-migrations is a file-based schema migration tool for ClickHouse that reads versioned SQL files from a directory and applies them in order, tracking which migrations have been run. It supports both the native clickhouse-driver (TCP) and the official clickhouse-connect (HTTP) driver, and is aware of ClickHouse cluster deployments, keeping migration state consistent across all nodes.

You write plain `.sql` files named like `001_init.sql`, `002_add_column.sql`, etc., each containing one or more SQL statements. The tool applies them via CLI commands, a Python API, or CI/CD integration. It can show migration status without applying anything, supports dry-run inspection, and offers optional rollback via paired `.down.sql` files. Multi-statement files and cluster-aware execution distinguish it from simpler alternatives.

Use it for:

• Manage schema changes in production ClickHouse clusters without manual coordination across nodes.
• Automate database initialization and schema updates in Docker or Kubernetes deployments via CLI.
• Track and inspect pending vs. applied migrations before running them in CI/CD pipelines.
• Roll back individual migrations using explicit hand-written down files when needed.
• Apply complex multi-statement migrations (e.g., table creation plus column additions) atomically.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Applies versioned SQL migrations to ClickHouse databases from the CLI, Python code, or CI/CD pipelines, with support for multi-statement files and cluster-aware state tracking.

Yes. The package is actively maintained, has low install friction, carries no known vulnerabilities, and solves a real problem for ClickHouse users. It is the most actively maintained migration tool for ClickHouse in Python and supports features (multi-statement files, cluster awareness) that alternatives lack. MIT licensing adds no restrictions.

Install

clickhouse-migrations on PyPI

pip install clickhouse-migrations

uv add clickhouse-migrations

poetry add clickhouse-migrations

Installing clickhouse-migrations

Before you install

Low friction: pure Python wheel with a single runtime dependency (clickhouse-driver). Actively maintained as of 2026-07-08 with recent releases.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal attribution requirements.

Quickstart

pip install clickhouse-migrations

# Create migrations/001_init.sql with SQL statements
clickhouse-migrations --db-host localhost --db-name mydb --migrations-dir ./migrations

# Or in Python:
from clickhouse_migrations.clickhouse_cluster import ClickhouseCluster
cluster = ClickhouseCluster(db_host="localhost")
cluster.migrate(db_name="test", migration_path="./migrations")

Requires a running ClickHouse server accessible at the specified host and port (default 9000 for clickhouse-driver, 8123 for clickhouse-connect).

Verify before relying

• Whether the tool handles concurrent migration attempts across cluster nodes without race conditions.
• Performance characteristics when applying many migrations to large ClickHouse clusters.
• Compatibility guarantees with specific ClickHouse server versions.

Package facts

Evidence: clickhouse_migrations-0.13.0-py3-none-any.whl

Keywords: clickhouse, migrations, migration, database, database-migration, schema-migration, sql, ddl, olap, cli

Tags

More Database packages