03 开通与迁移

学员课程 03 开通与迁移 的讲师配套材料。

时间安排

总计约 60 分钟，而时间的分布比总量更重要：大约 10-15 分钟的动手操作（第 1 步通过 Terraform 开通 ClickHouse Cloud 服务，约 2-3 分钟；第 2 步创建 trips_raw、写入区域参考 数据，并跑第一次空的 dbt run，再花几分钟），随后是 40-50 分钟无人值守的数据传输 （第 3 步的迁移脚本，以大约每秒 2 万行的速度搬运 5000 万行）。

这是整门课程中最重要的一条排期事实：一旦第 3 步开始，教室在接下来将近一个小时里 无事可做。 先把它启动，然后就在这里安排休息，或者利用这段等待时间补讲模块 02 中来不及讲的讲解要点，或者围绕各组 migration-plan.md 的决策做一场现场问答。 不要把休息安排在本模块的其他任何位置，就有意地放在这里。

讲解要点

• 本模块自己给出的理由，说明这个实验为什么用 Python 脚本而不是原生连接器来搬数据： Snowflake 不是 ClickPipes 支持的源（Kafka、S3、Kinesis 以及 Postgres/MySQL CDC 是； Snowflake 不是），而每一种替代方案（S3 导出、Snowflake -> Kafka -> ClickHouse）都是用实验规模的搭建换来一堆与迁移本身无关的 基础设施，一个 S3 桶、一个 IAM 角色、一个 Kafka 集群。
• Python 脚本真正的卖点，值得明确点出来：不需要 AWS 账号、自包含（两个新增包都装在 与 dbt 相同的 venv 里）、可以基于 max(pickup_at) 水位线用 --resume 续跑，而且足够透明，搭档可以直接读列映射，而不是在 UI 向导里一路点下去。
• 诚实地说明生产环境的替代方案：超过大约 5 亿行，或者在全表扫描的仓库成本很重要的场景下， S3 导出是更好的选择，并行导出、并行加载。Python 脚本适合实验规模，不是一个普适建议。
• 现在就预告迁移落差，尽管它要到模块 05 才被弥合：Snowflake 的 producer 在第 3 步运行的整段时间里一直在写入，所以 ClickHouse 会比 Snowflake 落后大约一次传输的时长。 这个落差在这里是预期之内的，而它恰恰就是模块 05 的切换所要弥合和测量的对象， 在有人问那 40-50 分钟的等待是不是在"浪费"数据之前，先把这一点说清楚。

常见故障

• 第 2 步中的第一次 dbt run 失败，报 Could not find profile named 'nyc_taxi_ch'。 实验里没有任何东西会自动创建 ClickHouse 的 nyc_taxi_ch dbt profile，尽管 dbt_project.yml 需要它。学员课程 03 开通与迁移 已经涵盖这一点：第 2 步的"配置 dbt profile"会带着搭档在这次 dbt run 之前，把一段 nyc_taxi_ch: 配置块合并进他们已有的 ~/.dbt/profiles.yml。 如果一位搭档跳过或复制错了那一步，就把他们指回那里，而不是在这里重讲一遍变通做法。
• 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。 说明当前 shell 里没有 设置 CLICKHOUSE_HOST，在 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ 下执行 source .clickhouse_state 后重试。

重置步骤

• 迁移脚本被中断：python scripts/02_migrate_trips.py --resume 会从水位线继续， 而不是重新开始整个 5000 万行的传输。
• ClickHouse Cloud 服务需要干净重建：在 workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ 下执行 source .env && ./teardown.sh（会销毁该服务，以及如果已经完成切换的话，还有 ClickHouse producer 容器），然后再跑一次 ./setup.sh。这不会触及模块 01 的 Snowflake 一侧，那边有自己的 teardown.sh，位于 workshop_public/snowflake_migration_lab/01-setup-snowflake/。
• 在这里做完整重置代价很高：一次全新的迁移要重付整个 40-50 分钟的传输时间。 只要 ClickHouse 服务本身仍然健康，就优先选择 --resume 或有针对性的修复，而不是 彻底销毁重建。