03 プロビジョニングと移行

学習者向けレッスン 03 プロビジョニングと移行 に対応するファシリテーター向けの手引きです。

所要時間

合計で約 60 分ですが、合計よりも時間の形が重要です。ハンズオン作業がおおよそ 10〜15 分 （Step 1 が Terraform 経由で ClickHouse Cloud サービスをプロビジョニングし、約 2〜3 分。 Step 2 が trips_raw を作成し、ゾーンの参照データをシードし、最初の空の dbt run を実行して さらに数分）、その後に 40〜50 分の無人データ転送（Step 3 の移行スクリプトが、おおよそ毎秒 20K 行で 5,000 万行を移動）が続きます。

これはワークショップ全体で最も重要なスケジュール上の事実です。Step 3 が始まると、会場は 1 時間近く何もすることがありません。 これを開始し、そこで休憩を取ってください。あるいは 会場に時間がなかったモジュール 02 のトークトラックの題材や、パートナーの migration-plan.md の判断についてのライブ Q&A にこの待ち時間を使ってください。このモジュール 内の他のどこにも休憩を入れず、意図してここに入れてください。

トークトラック

• このラボがネイティブコネクタではなく Python スクリプトでデータを動かす理由についての、 モジュール自身の根拠です。Snowflake はサポートされている ClickPipes のソースではありません （Kafka、S3、Kinesis、Postgres/MySQL の CDC はサポート対象ですが、Snowflake は違います）。 そして代替手段のいずれも（S3 エクスポート、Snowflake -> Kafka -> ClickHouse）、ラボ規模の セットアップを、移行そのものとは無関係なインフラ — S3 バケット、IAM ロール、Kafka クラスター — と引き換えにしてしまいます。
• Python スクリプトの実際の利点は、明示的に挙げる価値があります。AWS アカウントが不要、 自己完結している（新しく入る 2 つのパッケージは dbt と同じ venv に入る）、 max(pickup_at) のウォーターマークに対して --resume で再開可能、そして UI のウィザードを クリックしていくのではなくパートナーがカラムのマッピングを読める程度に透明である、という 点です。
• 本番向けの代替案は正直に名指ししてください。おおよそ 5 億行を超える場合、あるいはフル テーブルスキャンによるウェアハウスのコストが問題になる場合は、S3 エクスポートのほうが 適切な判断です。並列エクスポート、並列ロードになります。Python スクリプトはラボ規模に 適した選択で、普遍的な推奨ではありません。
• モジュール 05 がそれを埋めるとしても、移行のギャップについてここで予告してください。Step 3 が走っている間ずっと Snowflake の producer は書き込みを続けるため、ClickHouse は転送の長さ ぶんだけ Snowflake から遅れます。そのギャップはここでは想定どおりのもので、まさにモジュール 05 のカットオーバーがそれを埋めて計測するために作られています。40〜50 分の待ち時間が データを「無駄にしている」のではないかと誰かが尋ねる前に、これを伝えてください。

よくある失敗

• Step 2 の最初の dbt run が Could not find profile named 'nyc_taxi_ch' で失敗する。 dbt_project.yml がそれを要求しているにもかかわらず、ラボの 中には ClickHouse の nyc_taxi_ch dbt プロファイルを自動的に作成するものがありません。 学習者向けレッスンの 03 プロビジョニングと移行 がこれを扱っています。Step 2 の「Configure the dbt profile」で、この dbt run の前に 既存の ~/.dbt/profiles.yml へ nyc_taxi_ch: ブロックをマージする手順をパートナーに 案内しています。パートナーがその手順を飛ばしたりコピーを誤ったりした場合は、ここで 回避策を再説明するのではなく、その手順に戻すよう案内してください。
• Terraform の認証が 401 Unauthorized で失敗する。 CLICKHOUSE_TOKEN_KEY と CLICKHOUSE_TOKEN_SECRET を検証してください。どちらも ClickHouse Cloud UI の Settings -> API keys にあり、Admin スコープを持っている必要があります。
• 移行スクリプトが実行中に失敗する。 --resume で再実行してください。既に ClickHouse に ある max(pickup_at) でウォーターマークを取り、既にロード済みの行はスキップするため、 再開しても部分的で回復不能なロードになることはありません。
• 移行スクリプトがまったく接続できない。 Snowflake と ClickHouse のすべての環境変数が 設定されていることを確認し（echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD と echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD）、それから source .env && source .clickhouse_state して再試行します。
• dbt run が Connection refused または Unknown host で失敗する。 現在のシェルで CLICKHOUSE_HOST が設定されていません。 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ から source .clickhouse_state を実行して再試行してください。

リセット手順

• 移行スクリプトが中断した場合: python scripts/02_migrate_trips.py --resume は 5,000 万行の 転送全体をやり直すのではなく、ウォーターマークから続行します。
• ClickHouse Cloud サービスをきれいに作り直す必要がある場合: workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ から source .env && ./teardown.sh（サービスと、カットオーバーが既に済んでいる場合は ClickHouse の producer コンテナを破棄します）、その後もう一度 ./setup.sh を実行します。 これはモジュール 01 の Snowflake 側には触れません。そちらには workshop_public/snowflake_migration_lab/01-setup-snowflake/ に独自の teardown.sh が あります。
• ここでの完全リセットは高価です。移行をやり直すと 40〜50 分の転送すべてを払い直します。 ClickHouse サービス自体が健全なままである限り、完全なティアダウンよりも --resume か 的を絞った修正を選んでください。