05 基准测试与切换

学员课程 05 基准测试与切换 的讲师配套材料。

时间安排

约 45 分钟，分布在五个步骤上：添加 ClickHouse 仪表板（第 1 步，通过脚本导入只需几 分钟）、运行基准测试（第 2 步，七条查询乘三轮乘两个引擎，几分钟，基本无人值守， 但短到可以就这么看着）、切换本身（第 3 步，交互式，停止 producer、追赶增量、 刷新 dbt、启动 ClickHouse producer，每一步都是有意为之的顺序）、一致性验证 （第 4 步，很快），以及销毁环境（第 5 步）。

TODO：除了本模块 45 分钟的总时长之外，实验自带的材料没有给出每一步的时间， 在演练中确认时间的拆分，尤其是第 3 步的 --resume 追赶是否可靠地足够快 （按实验自己的描述是数秒到数分钟），以至于不需要任何缓冲时间。

讲解要点

• 这是把"准备好了"变成"已迁移"的模块。模块 03 和 04 证明了数据和流水线； 这个模块证明一个数字（基准测试），并证明写入路径真的转移了（切换）。
• 切换的顺序本身就是这里的内容，而不是形式：停止 Snowflake producer、运行 --resume 弥合落差、刷新 dbt，然后启动 ClickHouse producer。每一步都依赖它前面的 那一步，顺序搞错，正是一次静默的一致性失败发生的方式（见常见故障）。
• 明确说明为什么 --resume 在这里很快，而模块 03 里最初那次迁移却不是：它以 ClickHouse 中已有的 max(pickup_at) 作为水位线，只拉取增量，因此一个从模块 01 起就一直存在的落差会在数秒到数分钟内弥合，而不是又一次 40-50 分钟的批量传输。
• 把切换和模块 04 里 agg_hourly_zone_trips 的空表状态联系起来：一旦 ClickHouse producer 启动，它就会在整个实验中第一次被填充，因为它的过滤条件从来只匹配实时 producer 写入的行。这就是搭档从模块 04 起一直在问的那个问题的回报。
• 这是书面考核之前的最后一个模块，提醒教室把 migration-plan.md 和基准测试的 CSV 保存到第 5 步销毁两个云环境之后仍然能取到的地方。

常见故障

• 一位搭档通过 Superset UI 手工导入仪表板 ZIP，而不是运行 add_clickhouse_connection.sh。 仓库中提交的导出文件把 ClickHouse 主机名脱敏成了 your-instance.clickhouse.cloud；脚本会在导入前用 .env 里的值修补 URI， 但手工的 UI 导入会照原样使用那个占位主机名，连接将无法建立。让他们在导入之后编辑连接， 指向真实的 CLICKHOUSE_HOST 和凭据。
• 一位搭档跳过第 3 步的 --resume 追赶，直接完成了切换。 ClickHouse 会永久丢掉在模块 03 最初那次迁移到 producer 停止那一刻之间落入落差的所有行， 一次静默的一致性失败。第 4 步的一致性检查正是为了抓住这一点而存在的，但前提是它被执行了； 一位不做第 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。
• 基准测试对某条查询显示 N/A，最常见的是 Q7。 基准测试脚本连不上 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 恰好只需要这两个文件，别无其他。