00 Cài đặt

Tài liệu đồng hành của người hướng dẫn cho bài học của học viên 00 Cài đặt.

Thời lượng

Khoảng 30 phút. Đây là phần chuẩn bị trước, không phải nội dung của ngày học — hãy gửi nó cho các đối tác trước buổi học và xác nhận đã hoàn thành từ hôm trước, không phải vào sáng hôm đó. Không có phần nào ở đây tự chạy theo kiểu "bật lên rồi đi làm việc khác"; đó là năm lần cài công cụ, hai lần đăng ký tài khoản, một lần clone và hai lần dựng virtualenv, tất cả đều cần đối tác trực tiếp ngồi ở bàn phím suốt thời gian đó. Một đối tác đến lớp mà bỏ qua nó sẽ tốn khoảng 30 phút thời gian buổi học để bù lại tại chỗ, và phần thời gian đó bị lấy từ những gì module 01 đáng lẽ phải trình bày trong slot đó.

Nội dung trình bày

• Hãy định vị module này là phần hạ tầng, không phải nội dung chuyên môn: hai cloud (Snowflake là nguồn, ClickHouse Cloud là đích), hai adapter dbt, mỗi cloud một adapter, và cả hai adapter đều dùng chung một mức Python tối thiểu bắt buộc.
• Một điều đáng nói to lên, và nói nhiều hơn một lần: dbt-snowflake và dbt-clickhouse đều 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 dùng chung, mashumaro, ở cả hai adapter.
• Chỉ rõ hai virtualenv riêng biệt — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv và workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — và giải thích vì sao không thể gộp chúng thành một: hai adapter ghim các khoảng phiên bản phụ thuộc xung đột nhau.
• Khuyến khích đăng ký cả hai cloud ngay từ bây giờ, đừng để đến ngày học: cả trial Snowflake lẫn trial ClickHouse Cloud đều không được trở thành điểm nghẽn khi module 01 bắt đầu.

Các lỗi thường gặp

• Python 3.14+ làm hỏng dbt-snowflake và dbt-clickhouse thông qua mashumaro. Đây là lỗi tiêu biểu của module này, và cũng là lỗi nguy hiểm nhất, bởi vì ghim sai trình thông dịch sẽ không báo lỗi ở đây — nó chỉ lộ ra hai module sau đó dưới dạng một lỗi import dbt gây bối rối, thoạt trông chẳng liên quan gì tới phiên bản Python. Hãy xác nhận python3 --version báo 3.11, 3.12 hoặc 3.13 cho đúng trình thông dịch thực sự đứng sau từng virtualenv — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv và workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — chứ không chỉ bản mặc định của hệ thống — trước khi xác nhận một đối tác đã qua module này.
• TODO: không có chế độ lỗi nào khác cho module này được ghi lại trong README của chính lab. Hãy ghi lại ở đây bất cứ điều gì khác quan sát được trong buổi tổng duyệt (proxy hoặc firewall của công ty chặn pip install hay terraform init, thông báo về giấy phép Docker Desktop khi khởi chạy lần đầu, chậm trễ trong việc phê duyệt đăng ký trial).

Các bước reset

• Sai phiên bản Python đứng sau một venv: cd vào virtualenv của module bị sai — workshop_public/snowflake_migration_lab/01-setup-snowflake/ hoặc workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ — rồi xóa và dựng lại nó với trình thông dịch đã được ghim, ví dụ rm -rf .venv && python3.13 -m venv .venv && source .venv/bin/activate, và cài lại adapter của venv đó như hướng dẫn ở Bước 4 trong trang của học viên.
• Không có script teardown nào áp dụng cho module này — chưa có gì được cấp phát ở cả hai cloud. Nếu một đối tác cần làm lại một bước, chạy lại bước đó sẽ rẻ hơn là reset bất cứ thứ gì.
• TODO: hãy xác nhận trong buổi tổng duyệt xem việc phát trước một venv đã dựng sẵn có xứng đáng hay không đối với một lớp học có Wi-Fi không ổn định, thay vì cài trực tiếp năm công cụ và hai venv trong ngày học.