00 セットアップ

ツールチェーンをインストールし、2つのクラウドのトライアルアカウントを作成し、リポジトリをクローンし、両方の dbt 仮想環境を構築します — データに触れる前にマイグレーションが必要とするものすべてです。

開始チェックポイント

まだ何もインストールされていません。ターミナルと約30分が必要です。5つのコマンドラインツールのインストール、2つの無料クラウドトライアルへのサインアップ、リポジトリのクローン、Python 仮想環境 2つの構築を行います。

このワークショップは2つのクラウドをプロビジョニングします。ソースとして Snowflake、ターゲットとして ClickHouse Cloud です。そして、クラウドごとに1つずつ、2つの dbt アダプターをそれらに対して実行します。どちらのアダプターにも厳格なバージョン下限があり、実際に足をすくわれるのは Python です。 dbt-snowflake（および後で使う dbt-clickhouse）は Python 3.11、3.12、または 3.13 を必要とします。Python 3.14 以上では、両方のアダプターが依存している推移的依存関係の mashumaro が壊れます。ここで間違えても、この場では失敗しません。2モジュール先で、Python のバージョンとは一見まったく関係のなさそうな、分かりにくい dbt のインポートエラーとして表面化します。このモジュールでインタープリターを固定しておくことが、その失敗を起こさないための手立てです。

手順1 — ツールチェーンをインストールする

ツール	バージョン	用途
Terraform	>= 1.6	Snowflake と ClickHouse Cloud のインフラをプロビジョニングする
Docker Desktop	>= 24	trip プロデューサーと Superset を実行する
Python	3.11〜3.13	マイグレーションスクリプト、dbt、ユーティリティスクリプト — 下のコールアウトを参照
dbt Core	>= 1.8	Snowflake と ClickHouse のパイプライン
SnowSQL CLI	>= 1.2	ターミナルから Snowflake に対して SQL を実行する

Python のバージョンが重要です。 dbt-snowflake と dbt-clickhouse はどちらも Python 3.11、3.12、または 3.13 を必要とします。Python 3.14 以上では、両者が共有する mashumaro 依存関係が壊れます。システムの Python がすでに 3.14 以上の場合は、デフォルトを置き換えるのではなく、 3.13 を並べてインストールしてください（例: brew install python@3.13）。まさにこの理由から、下の手順4では python3.13 インタープリターを明示的に使います。

このワークショップでインストールするパッケージはすべて隔離された仮想環境に入れ、素のグローバルな pip install は決して使いません。手順4で必要な2つを用意します。

手順2 — 2つのクラウドアカウントを作成する

各クラウドにトライアルアカウントを1つずつ用意します。どちらも無料で、クレジットカードは不要です。

Snowflake トライアルアカウント — こちらがソース環境です。モジュール01では、ここにウェアハウス、データベース、Medallion パイプラインをプロビジョニングします。
ClickHouse Cloud トライアルアカウント — こちらがターゲット環境です。モジュール03でプロビジョニングし、マイグレーションが本格的に始まるまでは手を付けません。

いま両方にサインアップしておけば、モジュール01を始めたときにどちらのアカウントもボトルネックになりません。

手順3 — リポジトリをクローンする

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

このワークショップの以降のコマンドはすべて、このクローン内の workshop_public/snowflake_migration_lab にいることを前提としています。

手順4 — 2つの dbt 仮想環境を構築する

dbt-snowflake と dbt-clickhouse は競合する依存関係の範囲を固定しているため、1つの仮想環境を共有できません。アダプターごとに1つ、つまりマイグレーションのクラウド側ごとに1つ構築します。

dbt-snowflake、モジュール01でソースに対して使います。

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

# Use python3.13 explicitly if your system default is 3.14+
python3.13 -m venv .venv          # or: python3 -m venv .venv
source .venv/bin/activate
pip install "dbt-snowflake>=1.7,<2.0"
deactivate

dbt-clickhouse、モジュール03以降でターゲットに対して使います。

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse"
python3.13 -m venv .venv
source .venv/bin/activate
pip install "dbt-clickhouse>=1.8,<2.0" snowflake-connector-python clickhouse-connect
deactivate

各 .venv はそれぞれのモジュールディレクトリの中に置いたままにします。1つの環境で両方のアダプターを満たそうとするのではなく、必要な方をアクティブにし、切り替えるときに deactivate します。

完了の確認方法

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

terraform version                  # expect >= 1.6
docker --version                   # expect >= 24
python3 --version                  # expect 3.11, 3.12, or 3.13
snowsql --version                  # expect >= 1.2

source 01-setup-snowflake/.venv/bin/activate
dbt --version                      # expect dbt-snowflake >= 1.7
deactivate

source 03-migrate-to-clickhouse/.venv/bin/activate
dbt --version                      # expect dbt-clickhouse >= 1.8
deactivate

5つのコマンドはいずれも、示された下限以上のバージョンを出力するはずです。また、それぞれの dbt --version は、その venv にインストールしたアダプターを一覧に表示するはずです。

終了状態

ツールチェーンがインストールされ、両方のトライアルアカウントが有効になり、リポジトリがクローンされ、両方の dbt 仮想環境が構築されました。どちらのクラウドにもまだ何もプロビジョニングされていません。それはモジュール01から始まります。 01 ソース環境に進んで、マイグレーションの Snowflake 側を構築してください。