Why PyClickHouseMigrator?¶

PyClickHouseMigrator is a focused migration runner for Python teams that want to write ClickHouse DDL themselves, keep it in Git, and apply it through a small CLI or library.

It is deliberately not an ORM, schema diff engine, database provisioning tool, or deployment platform.

If you arrived here looking for "an Alembic for ClickHouse" or "golang-migrate but in Python": this is a runner in that family, built for ClickHouse only. The comparison table below says plainly where the alternatives are the better choice.

A good fit¶

Choose PyClickHouseMigrator when your team wants:

• plain SQL migration files with explicit up and down sections;
• exact statement boundaries instead of semicolon-based SQL splitting;
• stored SQL and SHA-256 checksums for applied migrations;
• preflight validation with EXPLAIN AST before execution;
• a dry-run that follows the same checksum and validation path;
• baseline adoption for an existing database;
• a small advisory lock for common CI/CD races;
• cluster-aware migrator service tables while keeping user DDL explicit.

It fits particularly well when Python already exists in the delivery environment and the team prefers reviewable SQL over generated schema changes.

Choose another approach when¶

Use another tool or process when you need:

• declarative schema inspection and automatic diff generation;
• one migration system already standardized across many database engines;
• a central UI with approvals, RBAC, environment promotion, and audit workflows;
• ORM-generated migrations;
• automatic creation of the target database;
• automatic rewriting of user DDL with ON CLUSTER;
• transactional guarantees across multiple ClickHouse DDL statements.

No migration runner can make ClickHouse DDL transactional. Design multi-statement migrations so that partial execution can be diagnosed and safely resumed.

Compare the operating models¶

The ClickHouse schema migration tools guide gives a broader ecosystem overview and recommends choosing for team familiarity and operating process, not for feature count alone.

What the migrator records¶

After a migration succeeds, db_migrations stores its name, applied timestamp, up SQL, down SQL, and checksum. Future runs compare applied history with the current files before executing pending SQL.

That model provides two useful boundaries:

1. application schema changes remain ordinary SQL reviewed in Git;
2. migration state remains inspectable inside ClickHouse.

See the migration format for exact parsing and checksum rules.

Production deployment flow¶

Run migrations once per environment, before the application rollout:

reviewed migration files
          │
          ▼
dedicated migration job
  connect → lock → verify → validate → apply → record
          │
          ▼
application rollout

A typical job uses the same artifact that was reviewed:

migrator up --dry-run
migrator up

Keep a single migration runner even when advisory locking is enabled. The lock reduces common races; it is not a deployment orchestrator.

For concrete pipelines, see CI/CD usage, Docker usage, and cluster mode.

Boundaries to accept before adoption¶

• ClickHouse DDL is not transactional; a later statement can fail after earlier statements ran.
• SQL is trusted input and executes as written.
• rollback SQL is written by the migration author, not generated.
• baseline records history but does not compare it with the live schema.
• preflight validation cannot prove that production execution will succeed or be operationally cheap.
• cluster mode changes migrator service tables, not user migration SQL.

Read Known limitations before using the tool in production.

Start with the smallest proof¶

Install the CLI, create one migration against a disposable ClickHouse database, inspect the dry-run, and apply it:

uv tool install py-clickhouse-migrator
export CLICKHOUSE_MIGRATE_URL=clickhouse://default@localhost:9000/mydb
migrator init
migrator new create_events
migrator up --dry-run
migrator up

Continue with the migration format when that operating model matches your team.