ClickHouse のスキーマ移行ツール

スキーマ管理とは、バージョン管理の原則をデータベースのスキーマに適用する取り組みです。一般に、テーブルやカラム、その関係に対する変更を追跡・自動化し、スキーマ更新を環境を問わず再現可能で、監査可能かつ一貫したものにすることを指します。スキーマ管理が重要になるのは、新しいユースケースやパフォーマンス optimization のために、データベース内のデータ構造を変更する必要がある場合です。

スキーマ管理ツールを使うと、アプリケーションのデプロイとあわせてスキーマ変更を自動化できます。新しいアプリケーションのバージョンをデプロイするうえで、スキーマ変更が前提条件になることはよくあります。また、これらのツールは、ユーザーがデータベースのあるバージョンから別のバージョンへ移行する際に使われることから、「スキーマ移行」や「database migration」ツールとも呼ばれます。

スキーマ管理ツールがない場合、データベースの変更は手作業となり、エラーが発生しやすく、チームや環境をまたいだ調整も難しくなります。もちろん、データベースに対して直接 DDL を実行することもできますが、こうしたツールを使うことで、バージョン管理、自動デプロイ、ロールバックのサポート、監査証跡の確保が可能になります。特に ClickHouse では、一部の DDL 変更は高コストだったり元に戻せなかったりするため、レビュー手順を含む体系的な移行プロセスがとりわけ重要です。

スキーマ管理ツールは、一般的に2つの種類に分けられます。

これらのツールでは、状態 A から状態 B への移行方法を記述した、バージョン付きの SQL ファイルを使用します。CREATE TABLE、ALTER TABLE、DROP COLUMN のような明示的な DDL ステートメントをファイルに記述します。ツールはそのファイルを順番に実行し、どのファイルが適用済みかを追跡します。このカテゴリでは、実行する SQL を正確に指定します。

例: Golang Migrate、Goose、Flyway。

これらのツールでは、まずユーザーが望ましい状態のスキーマを定義します。ツールは現在のデータベースと望ましい状態との差分を検出し、必要な移行を生成して適用します。このアプローチにより、移行を手作業で作成する負担やスキーマドリフトを軽減できます。このカテゴリでは、実行する SQL はツールが厳密に決定します。

例: Atlas と Liquibase。

データベースのスキーマ変更よりも、データ自体の変換に重点を置くツールという 3 つ目のカテゴリもあります。

例: dbt。

この記事では、データベースのスキーマ変更向けのツールだけを扱います。

チームの運用方針に合ったツールを選んでください。命令型ツールでは、どの DDL が実行されるかを完全に把握できますが、スキーマドリフトの特定と管理には継続的な注意が必要です。宣言型ツールは保守作業の多くを自動化し、スキーマドリフトの防止にも役立ちますが、ClickHouse に適用する前に、生成されたプランを必ず確認してください。自動生成されたプランに、想定外の mutation や高コストな rewrite が含まれていないことを確認してください。

多くの場合、使い慣れたエコシステムを基準にツールを選ぶことになるでしょう。チームが Go を主に使っているなら、Golang Migrate や Goose は自然な選択肢に感じられるはずです。Java のエコシステムで開発しているなら、すでに Flyway や Liquibase を導入しているかもしれません。インフラストラクチャ チームが Terraform や Infrastructure as Code のパターンを採用しているなら、Atlas の宣言型モデルも無理なく受け入れられるでしょう。チームがすでに理解しているものを選ぶことには、確かな価値があります。最良のツールとは、実際に採用され、継続的に使われるツールです。

スキーマ変更が組織内でどのように進むかを考えてみてください。次のうち何が必要かを検討しましょう。

• Goose や Golang Migrate のような、シンプルな「SQL を書いて、CI で実行して、それで完了」というワークフロー。
• Bytebase や Liquibase のような、承認ワークフロー、監査証跡、RBAC などを備えた仕組み。
• Atlas のような、スキーマを宣言的に定義し、ツールが差分を判断する方式。

要件とプロセスに合ったツールを選んでください。

以下は、成熟度、ClickHouse との互換性、コミュニティでの採用状況、運用面での適合性を考慮して、ClickHouse ユーザー向けに一般的に推奨しているツールです。

Atlas は、宣言的なアプローチを採る schema-as-code ツールです。望ましいスキーマの状態を HCL または SQL で定義すると、Atlas が現在のデータベースを調査し、差分を計算して移行計画を生成し、必要に応じてレビュー後に適用します。

ClickHouse で相性がよい理由: Atlas は ClickHouse を手厚くサポートしており、テーブル、ビュー、materialized view、プロジェクション、パーティション、UDFs に対応しています。Atlas は 2025 年 9 月の v0.37 でクラスターサポートを追加しました。HCL とプレーンな SQL スキーマ定義の両方をサポートしています。

注意すべき点: Atlas の ClickHouse ドライバーは、Pro プランまたは trial でのみ利用できます。Atlas は移行計画を生成しますが、その計画にかかるコストまでは判断しません。たとえばカラム型の変更のように、見た目は単純な差分でも、複数テラバイト規模のテーブルで高コストな mutation をトリガーする可能性があります。生成された計画は、適用前に必ず確認してください。

最適な用途: infrastructure-as-code のワークフローと自動ドリフト検出を求めるチーム。

• Type: 宣言的
• Language: Go、単一のバイナリとして配布
• License and availability: Open Core。Atlas CLI には Apache 2.0 のコミュニティ版がありますが、ClickHouse サポートには Pro プランまたは trial が必要です
• Cluster support: はい

Golang Migrate は、シンプルで広く使われている移行ツールです。up と down の手順を定義したバージョン管理付きの SQL ファイルを作成すると、このツールがそれらを順番に適用し、ClickHouse データベース内の schema_migrations テーブルで状態を管理します。

ClickHouse で使いやすい理由: シンプルで柔軟だからです。実行したい ClickHouse DDL をそのまま記述できます。ランタイム依存のない単一の Go バイナリなので、CI/CD パイプラインや Docker コンテナーにも簡単に組み込めます。

注意点: 移行ファイルに複数のステートメントが含まれていて、その途中で 1 つでも失敗すると、データベースが一部だけ適用された中途半端な状態になり、手動での対応が必要になることがあります。これは、1 ファイルにつき 1 ステートメントとする運用を徹底することで回避できます。

最適な用途: シンプルさを重視し、ClickHouse インスタンスに対して実行する SQL を完全に制御したいチーム。

• Type: 命令型
• Language: Go
• License: オープンソース、MIT
• Cluster support: はい

Goose は、Golang Migrate と似た思想を持つ、もう 1 つの Go 製の移行実行ツールです。バージョン付きの SQL ファイルや、複雑なロジック向けの Go 関数を記述すると、Goose がそれらを順番に適用し、ClickHouse のバージョンテーブルで状態を追跡します。

ClickHouse と相性がよい理由: Goose は SQLファースト で、設定は最小限で済み、CLI もシンプルで、CI/CD にも簡単に組み込めます。さらに、移行を Go 関数として記述することもできるため、純粋な SQL だけでは表現できない複雑なロジックにも柔軟に対応できます。

注意点: Goose には、スキーマ差分の取得や移行の自動生成機能はありません。

最適なケース: すでに Goose を使っているチームや、Golang Migrate よりも Goose の移行ファイル規約を好むチームに適しています。

• Type: 命令型
• Language: Go、単一バイナリとして配布
• License: オープンソース、MIT
• Cluster support: No

以下のツールも ClickHouse で利用できます。使用しているスタックやワークフローによっては、こちらの方が適している場合もあります。ただし、通常は上記のツールを推奨します。