00 Chuẩn bị

Điểm khởi đầu

Chưa cài gì cả. Bạn cần một terminal và khoảng 30 phút: cài năm công cụ dòng lệnh, đăng ký hai bản dùng thử cloud miễn phí, clone repo, và dựng hai virtualenv Python.

Vì sao

Workshop này cấp phát hai cloud — Snowflake làm nguồn, ClickHouse Cloud làm đích — và chạy hai adapter dbt trên chúng, mỗi cloud một adapter. Cả hai adapter đều có ngưỡng phiên bản tối thiểu bắt buộc, và cái thực sự gây đau là Python: dbt-snowflake (và dbt-clickhouse, dùng ở phần sau) yêu cầu Python 3.11, 3.12 hoặc 3.13. Python 3.14+ làm hỏng một phụ thuộc bắc cầu, mashumaro, mà cả hai adapter đều dựa vào. Làm sai điều này lúc này thì nó không lỗi ở đây — nó lộ ra hai module sau dưới dạng một lỗi import dbt gây bối rối mà nhìn bề ngoài chẳng liên quan gì đến phiên bản Python của bạn. Việc ghim interpreter ngay trong module này là điều khiến lỗi đó không xảy ra.

Bước 1 — Cài bộ công cụ

Mọi package bạn cài cho workshop này đều đi vào một virtualenv tách biệt, không bao giờ là một lệnh pip install toàn cục trơ trọi — Bước 4 dựng hai virtualenv bạn cần.

Bước 2 — Tạo hai tài khoản cloud

Bạn cần một tài khoản dùng thử ở mỗi cloud, cả hai đều miễn phí và không cần thẻ tín dụng:

• Tài khoản dùng thử Snowflake — đây là môi trường nguồn. Module 01 cấp phát một warehouse, một database và pipeline Medallion ở đây.
• Tài khoản dùng thử ClickHouse Cloud — đây là môi trường đích. Nó sẽ nằm im cho đến khi module 03 cấp phát nó và cuộc di chuyển bắt đầu thực sự.

Đăng ký cả hai ngay bây giờ nghĩa là không tài khoản nào trở thành vật cản khi bạn bắt đầu module 01.

Bước 3 — Clone repository

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

Mọi lệnh trong phần còn lại của workshop này đều giả định bạn đang đứng ở workshop_public/snowflake_migration_lab bên trong bản clone này.

Bước 4 — Dựng hai virtualenv dbt

dbt-snowflake và dbt-clickhouse ghim các khoảng phụ thuộc xung đột nhau, nên chúng không thể dùng chung một virtualenv — bạn dựng một virtualenv cho mỗi adapter, tức mỗi phía cloud của cuộc di chuyển.

dbt-snowflake, dùng cho phía nguồn trong module 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, dùng cho phía đích bắt đầu từ module 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

Mỗi .venv nằm bên trong thư mục module của riêng nó — bạn kích hoạt cái mình cần và deactivate khi chuyển sang cái kia, thay vì cố làm cho một môi trường thỏa mãn cả hai adapter.

Cách kiểm tra bạn đã xong

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

Cả năm lệnh đều phải in ra một phiên bản bằng hoặc cao hơn ngưỡng tối thiểu được nêu, và mỗi lệnh dbt --version phải liệt kê đúng adapter bạn vừa cài vào venv đó.

Trạng thái kết thúc

Bộ công cụ đã được cài, cả hai tài khoản dùng thử đã hoạt động, repo đã được clone, và cả hai virtualenv dbt đã được dựng. Chưa có gì được cấp phát ở cả hai cloud — việc đó bắt đầu ở module 01. Tiếp tục sang 01 Môi trường nguồn để dựng phía Snowflake của cuộc di chuyển.