05 ベンチマークとカットオーバー

学習者向けレッスン 05 ベンチマークとカットオーバー に対応するファシリテーター向けの手引きです。

所要時間

5 つの手順を通じて約 45 分。ClickHouse のダッシュボードの追加（Step 1、スクリプト化された インポートで数分）、ベンチマークの実行（Step 2、7 本のクエリ × 3 回 × 2 エンジン — 数分で、 大半は無人だが、そのまま眺めていられる程度に短い）、カットオーバー本体（Step 3、対話的 — producer を止め、差分を追いつかせ、dbt をリフレッシュし、ClickHouse の producer を起動する。 それぞれが順序どおりの意図的な手順）、パリティの検証（Step 4、短時間）、そしてティアダウン （Step 5）です。

TODO: ラボ自身の資料には、モジュール全体の 45 分という合計を超える手順ごとの所要時間は 示されていません。とくに Step 3 の --resume による追いつきパスが、バッファを必要としない ほど確実に速いか（ラボ自身の説明によれば数秒から数分）を、リハーサルで内訳とともに確認して ください。

トークトラック

• これは「準備完了」を「移行済み」に変えるモジュールです。モジュール 03 と 04 はデータと パイプラインを証明しました。このモジュールは数字（ベンチマーク）を証明し、書き込み経路が 実際に移ること（カットオーバー）を証明します。
• カットオーバーの順序は形式ではなく、ここでの中身そのものです。Snowflake の producer を 停止し、--resume を実行してギャップを埋め、dbt をリフレッシュし、それから ClickHouse の producer を起動します。各手順はその前の手順に依存しており、順序を違えて実行することが、 まさに静かなパリティ失敗の起き方です（「よくある失敗」を参照）。
• モジュール 03 の当初の移行が速くなかったのに対し、なぜここでの --resume が速いのかを 明示的に伝えてください。既に ClickHouse にある max(pickup_at) でウォーターマークを取り、 差分だけを引くため、モジュール 01 から開いていたギャップも、40〜50 分のバルク転送を もう一度行うのではなく、数秒から数分で埋まります。
• カットオーバーをモジュール 04 の agg_hourly_zone_trips の空の状態に結びつけてください。 ClickHouse の producer が起動すると、ラボ全体で初めてそれが埋まります。フィルターが ライブ producer の行にしか一致しなかったからです。これは、パートナーがモジュール 04 から ずっと尋ねてきた質問に対する報酬です。
• これは筆記の評価の前の最後のモジュールです。Step 5 のティアダウンで両方のクラウド環境が 削除される前に、migration-plan.md とベンチマークの CSV を手の届く場所に保管しておくよう 会場に念を押してください。

よくある失敗

• パートナーが add_clickhouse_connection.sh を実行するのではなく、Superset の UI から ダッシュボードの ZIP を手作業でインポートする。 コミットされているエクスポートは ClickHouse のホストが your-instance.clickhouse.cloud に伏せられています。スクリプトは インポート前に .env から URI を修正しますが、UI からの手作業のインポートでは プレースホルダーのホストがそのまま使われ、接続できません。その場合は後から接続を編集して、 実際の CLICKHOUSE_HOST と認証情報を指すようにしてもらってください。
• パートナーが Step 3 の --resume による追いつきパスを飛ばして、そのままカットオーバー してしまう。 モジュール 03 の当初の移行から producer が停止した瞬間までのギャップに 入った行は、ClickHouse から恒久的に失われます。静かなパリティ失敗です。Step 4 のパリティ チェックはこれを捕まえるために作られていますが、実行された場合に限ります。Step 4 を 実行せずにベンチマークの記述へ直行したパートナーは、失われた行に気付きません。
• 片付け好きのパートナーによって、Snowflake の producer がモジュール 01 か 02 の時点で すでに停止されていた。 producer が継続して動いていなければ、カットオーバーがギャップを 計測する対象が何もありません。これはこの手順だけでなく、カットオーバーのデモンストレーション 全体を壊します。もしそうなっていた場合、正直な対処は producer を再起動し、数分間書き込ませて 実際のギャップを作ってから進めることです。開いたことのないギャップを後付けで実演する方法は ありません。
• パリティチェックが失敗する（差分が 0.01% より大きい）。 追いつきパスをもう一度実行して 再確認します: python scripts/02_migrate_trips.py --resume の後に bash scripts/01_verify_migration.sh。
• Superset が 403 Forbidden を表示する。 セッションの cookie が期限切れです。 http://localhost:8088 でログアウトして再ログインし、その後 superset/add_clickhouse_connection.sh を再実行します。
• ベンチマークがあるクエリ、多くの場合 Q7 に N/A を表示する。 ベンチマークスクリプトが ClickHouse に接続できませんでした。CLICKHOUSE_HOST が設定されていること（source .clickhouse_state）と、サービスが稼働していることを確認します。

リセット手順

• パリティチェックが失敗した場合: python scripts/02_migrate_trips.py --resume の後に bash scripts/01_verify_migration.sh を再実行します。
• カットオーバーを取り消す必要がある場合（逆カットオーバー）: docker stop nyc_taxi_ch_producer を実行し、その後 workshop_public/snowflake_migration_lab/01-setup-snowflake/superset から docker-compose --env-file ../.env up -d producer で Snowflake の producer を戻します。
• 環境の完全リセット: workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ からの source .env && ./teardown.sh は、ClickHouse Cloud サービスと（カットオーバーが済んでいる 場合は）ClickHouse の producer コンテナを破棄します。Snowflake はこのスクリプトでは 触れられません。workshop_public/snowflake_migration_lab/01-setup-snowflake/ からの source .env && ./teardown.sh で個別に破棄してください。
• どちらのティアダウンを実行する前でも、migration-plan.md とベンチマークの CSV （scripts/benchmark_results_<timestamp>.csv）が手の届く場所に保存されていることを確認して ください。この後は両方のクラウド環境が消え、モジュール 06 が必要とするのはまさにこの 2 つの ファイルだけです。