Skip to content

PyClickHouseMigrator

PyClickHouseMigrator is a SQL-first ClickHouse migration runner for teams that keep schema changes in Git and run them through a small, predictable CLI.

It stores migration state inside ClickHouse, validates checksums, supports rollback SQL, handles advisory locking, and works with single-node or cluster deployments.

Install

pip install py-clickhouse-migrator

With uv:

uv add py-clickhouse-migrator

The CLI command is:

migrator --help

Quick start

Set the ClickHouse connection URL. The database in the URL must already exist.

export CLICKHOUSE_MIGRATE_URL=clickhouse://default@localhost:9000/mydb

Create a migrations directory and a first migration:

migrator init
migrator new create_users_table

Edit the generated file in ./db/migrations:

-- migrator:up
-- @stmt
CREATE TABLE IF NOT EXISTS users
(
    id UInt64,
    name String,
    created_at DateTime DEFAULT now()
)
ENGINE = MergeTree
ORDER BY id

-- migrator:down
-- @stmt
DROP TABLE IF EXISTS users

Preview what will run:

migrator up --dry-run

Apply pending migrations:

migrator up

Check status:

migrator show

Rollback the last applied migration:

migrator rollback

Guides

Examples