---
id: clickhouse-migrations
version: "0.13.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# clickhouse-migrations — Simple file-based migrations for clickhouse

License: permissive · Maintenance: active · Downloads: 74.8K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 74.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

clickhouse schema migrations, database migration tool, sql file versioning, clickhouse cluster migrations, ddl migration management, clickhouse cli tool, multi-statement migrations, schema-migration, clickhouse, devops

[View on SkillFed](https://skillfed.io/packages/clickhouse-migrations) · [View on PyPI](https://pypi.org/project/clickhouse-migrations/)