00 环境准备

安装工具链、创建两个云试用账号、克隆仓库并构建两个 dbt 虚拟环境，即迁移在你接触数据之前所需的一切。

起点

此时还什么都没装。你需要一个终端和大约 30 分钟：安装五个命令行工具、注册两个免费云试用、克隆仓库，并构建两个 Python 虚拟环境。

本课程会开通两个云，Snowflake 作为源、ClickHouse Cloud 作为目标，并针对它们运行两个 dbt 适配器，每个云一个。两个适配器都有硬性版本下限，而真正会咬人的那个是 Python： dbt-snowflake（以及稍后用到的 dbt-clickhouse）要求 Python 3.11、3.12 或 3.13。 Python 3.14+ 会破坏两个适配器共同依赖的一个传递依赖 mashumaro。现在弄错的话，问题不会在这里暴露，它会在两个模块之后浮现为一个令人困惑的 dbt 导入错误，表面上看和你的 Python 版本毫无关系。在本模块里把解释器版本钉死，正是让那个故障不发生的办法。

步骤 1：安装工具链

工具	版本	用途
Terraform	>= 1.6	开通 Snowflake 和 ClickHouse Cloud 基础设施
Docker Desktop	>= 24	运行行程生产者和 Superset
Python	3.11–3.13	迁移脚本、dbt 和各类工具脚本，见下方提示
dbt Core	>= 1.8	Snowflake 与 ClickHouse 流水线
SnowSQL CLI	>= 1.2	从终端对 Snowflake 执行 SQL

Python 版本很关键。 dbt-snowflake 和 dbt-clickhouse 都要求 Python 3.11、3.12 或 3.13。Python 3.14+ 会破坏它们共用的 mashumaro 依赖。如果你的系统 Python 已经是 3.14+，请在其旁边额外安装 3.13（例如 brew install python@3.13），而不是替换你的默认版本，下面的步骤 4 显式使用 python3.13 解释器正是出于这个原因。

本课程中安装的每个包都进入隔离的虚拟环境，绝不做裸的全局 pip install，步骤 4 会建好你需要的那两个。

步骤 2：创建两个云账号

你需要在每个云中各有一个试用账号，两者都免费且无需信用卡：

Snowflake 试用账号：这是源环境。模块 01 会在这里开通一个 warehouse、数据库和 Medallion 流水线。
ClickHouse Cloud 试用账号：这是目标环境。在模块 03 开通它、迁移正式开始之前，它保持不动。

现在就把两个都注册好，意味着一旦开始模块 01，两个账号都不会成为阻塞项。

步骤 3：克隆仓库

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

本课程后续的每条命令都假设你位于此克隆内的 workshop_public/snowflake_migration_lab 目录中。

步骤 4：构建两个 dbt 虚拟环境

dbt-snowflake 和 dbt-clickhouse 钉死了互相冲突的依赖版本范围，因此它们不能共用一个虚拟环境，你为每个适配器、也就是迁移的每一侧云各建一个。

dbt-snowflake，在模块 01 中针对源端使用：

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

# Use python3.13 explicitly if your system default is 3.14+
python3.13 -m venv .venv          # or: python3 -m venv .venv
source .venv/bin/activate
pip install "dbt-snowflake>=1.7,<2.0"
deactivate

dbt-clickhouse，从模块 03 起针对目标端使用：

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse"
python3.13 -m venv .venv
source .venv/bin/activate
pip install "dbt-clickhouse>=1.8,<2.0" snowflake-connector-python clickhouse-connect
deactivate

每个 .venv 都留在它自己的模块目录内，你激活需要的那个，切换时执行 deactivate，而不是试图让一个环境同时满足两个适配器。

如何确认已完成

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

terraform version                  # expect >= 1.6
docker --version                   # expect >= 24
python3 --version                  # expect 3.11, 3.12, or 3.13
snowsql --version                  # expect >= 1.2

source 01-setup-snowflake/.venv/bin/activate
dbt --version                      # expect dbt-snowflake >= 1.7
deactivate

source 03-migrate-to-clickhouse/.venv/bin/activate
dbt --version                      # expect dbt-clickhouse >= 1.8
deactivate

这五条命令都应打印出不低于所示下限的版本号，并且每次 dbt --version 都应列出你刚装进那个 venv 的适配器。

结束状态

工具链已安装、两个试用账号均已可用、仓库已克隆、两个 dbt 虚拟环境均已构建。两个云中都还没有开通任何资源，那从模块 01 开始。继续前往 01 源环境，去搭建迁移的 Snowflake 一侧。

起点

为什么