> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-revert-104359-revert-104251-parquet-single.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse のスキーマ移行ツール

> ClickHouse のスキーマ移行ツールと、時間の経過とともに変化するデータベーススキーマを管理する方法について学びます。

<div id="what-is-schema-management">
  ## スキーマ管理とは何ですか？
</div>

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

<div id="why-is-it-important">
  ### なぜ重要なのでしょうか？
</div>

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

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

<div id="types-of-schema-management-approaches">
  ### スキーマ管理のアプローチの種類
</div>

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

<div id="imperative">
  #### 命令型
</div>

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

例: Golang Migrate、Goose、Flyway。

<div id="declarative">
  #### 宣言型
</div>

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

例: Atlas と Liquibase。

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

例: dbt。

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

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

<div id="what-to-consider-when-choosing-a-tool">
  ## ツールを選ぶ際の考慮点
</div>

<div id="what-does-your-team-already-use">
  ### チームですでに使っているものは何ですか？
</div>

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

<div id="what-is-your-desired-process">
  ### 望ましいプロセスは何ですか？
</div>

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

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

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

<div id="recommended-tools">
  ## 推奨ツール
</div>

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

<div id="atlas">
  ### Atlas
</div>

[Atlas](https://atlasgo.io/guides/clickhouse) は、宣言的なアプローチを採る 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:** はい

<div id="golang-migrate">
  ### Golang Migrate
</div>

[Golang Migrate](https://github.com/golang-migrate/migrate/tree/master/database/clickhouse) は、シンプルで広く使われている移行ツールです。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:** はい

<div id="goose">
  ### Goose
</div>

[Goose](https://github.com/pressly/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

<div id="other-tools-in-the-ecosystem">
  ## エコシステム内のその他のツール
</div>

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

| ツール                                                                                           | ライセンス   | 向いているケース                                                                 |
| :-------------------------------------------------------------------------------------------- | :------ | :----------------------------------------------------------------------- |
| [Bytebase](https://docs.bytebase.com/introduction/supported-databases)                        | オープンコア  | 複数環境にまたがるガバナンス、承認ワークフロー、監査証跡が必要な大規模組織                                    |
| [Flyway](https://documentation.red-gate.com/fd/supported-databases-for-flyway-143754067.html) | オープンソース | すでに Flyway や JVM ベースのインフラストラクチャを標準化しているチーム                               |
| [Liquibase](https://github.com/MEDIARITHMICS/liquibase-clickhouse)                            | オープンコア  | 複数のデータベースで Liquibase を使用しており、一貫性を重視するチーム                                 |
| [`clickhouse-migrations` for Node.js](https://www.npmjs.com/package/clickhouse-migrations)    | オープンソース | シンプルで ClickHouse に特化した実行ツールを求める Node.js または TypeScript のチーム              |
| [Houseplant](https://github.com/juneHQ/houseplant)                                            | オープンソース | 環境対応の ClickHouse 固有ツールを求める Python チーム                                    |
| [Sqitch](https://sqitch.org/docs/manual/sqitchtutorial-clickhouse/)                           | オープンソース | ネイティブの ClickHouse client を使ったデプロイスクリプトや、複雑なデプロイメント全体にわたる明示的な依存関係管理を好むチーム |
| [Alembic](https://alembic.sqlalchemy.org/) with SQLAlchemy                                    | オープンソース | データベースアクセスに SQLAlchemy をすでに使用している Python チーム                             |
| [`clickhouse-migrations` for Python](https://github.com/zifter/clickhouse-migrations)         | オープンソース | ClickHouse クラスターのサポートがある、シンプルなファイルベースの移行実行ツール、CLI、ライブラリを求める Python チーム   |