01 源端环境

学员课程 01 源端环境 的讲师配套材料。

时间安排

总计约 45 分钟。第 2 步（./setup.sh）是唯一一段无人值守的时间，大约 5-10 分钟， 其中大部分是 TABLE(GENERATOR) 合成数据的写入，值得用讲解填满，而不是默默看着它跑； 这是使用下面讲解要点的好时机。剩下的时间（第 1 步和第 3-5 步）需要搭档在键盘前： 配置凭据、验证 producer 和 Superset 已启动、启动 dbt 刷新循环，以及通读那七条查询。

讲解要点

• 这个模块存在的意义是构建一个值得迁移的源端：一个 VARIANT 列、一条 CDC stream、两个定时任务，以及在这一切之上读取数据的 BI 层，而不是一张玩具表。 其中每一项都会在模块 02 变成一个具体的迁移决策。
• 在架构图上把 Medallion 的形状走一遍：NYC_TAXI_DB 内部的 RAW -> STAGING -> ANALYTICS， 以及让它独立于 dbt 持续运转的那两个对象， TRIPS_CDC_STREAM 和两个定时任务。
• 指出查询库（第 5 步），尽管搭档要到模块 02 才会真正翻译这些查询，七条查询中的每一条 都已经带有一段注释，勾勒出 ClickHouse 一侧的写法，所以搭档现在就可以开始做模式匹配。
• 明确说明，并在模块结束时再重复一次：把 producer 和 dbt 刷新循环留着继续运行。 模块 05 的切换会测量 producer 在迁移期间于 Snowflake 与 ClickHouse 之间造成的精确落差， 而一位在这里"顺手收拾干净"把它停掉的搭档，会在三个模块之后悄无声息地毁掉那个演示。

常见故障

• terraform init 报 provider 错误。 确认 Terraform >= 1.6，并且机器能访问 Terraform registry。
• snowsql 连接被拒绝。 检查 SNOWFLAKE_ORG 和 SNOWFLAKE_ACCOUNT；用 snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER} 直接测试。
• dbt run 报 relation not found。 先运行 ./setup.sh --skip-seed，它会创建 数据库结构，并确认 profiles.yml 指向 NYC_TAXI_DB。
• Superset 显示 connection refused。 Superset 在 docker-compose up 之后需要 大约 60 秒完成初始化；如果超过这个时间仍然不可用，检查 docker logs nyc_taxi_superset。
• 数据写入比搭档预期的更久。 TABLE(GENERATOR) 的 insert 会在大约 10-12 分钟内 生成 5000 万行；随后那条为全部 5000 万行填充 TRIP_METADATA JSON 列的 UPDATE， 在 SMALL 规格的仓库上可能再增加 15-20 分钟。对于一个大 VARIANT 列的更新，这是正常的 Snowflake 行为，不是卡住，在搭档开始排查一个本就工作正常的脚本之前，先说清楚这一点。
• 一位搭档在这个模块看起来"做完了"之后把行程 producer 停掉了。 它并没有做完， 模块 02 到 05 都依赖它保持在线，而模块 05 的切换更是专门在测量它造成的落差。 这是整门课程中最具破坏性的一次"手太勤"的错误；要明确说出来，而且不止一次。

重置步骤

• 重新开通环境但不重付约 10 分钟的数据加载代价：./setup.sh --skip-seed （基础设施已存在，且 TRIPS_RAW 已有数据）。
• 只是在迭代 Terraform 或 SQL 改动：只用 ./setup.sh --skip-seed。
• 只迭代 dbt 模型，完全跳过 Superset： ./setup.sh --skip-seed --skip-superset。
• 测试 Terraform 改动但不重跑 dbt：加上 --skip-dbt。
• 在 dbt 模型 schema 变更之后，强制做一次完整的增量重建：--full-refresh （与 --skip-seed 组合，以避免同时重付数据加载的代价）。
• 只有在环境彻底无法恢复时才做完整重置：在 workshop_public/snowflake_migration_lab/01-setup-snowflake/ 下执行 source .env && ./teardown.sh，然后再普通地重跑一次 ./setup.sh。这是破坏性操作，并且会重付完整的约 10-12 分钟数据写入， 不要把它当作处理某位搭档卡住时的第一反应。