01 Môi trường nguồn

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 01 Môi trường nguồn.

Thời lượng

Khoảng 45 phút. Bước 2 (./setup.sh) là đoạn duy nhất tự chạy — khoảng 5-10 phút, phần lớn là quá trình seed dữ liệu tổng hợp bằng TABLE(GENERATOR) — và đây là lúc nên nói chuyện thay vì ngồi xem trong im lặng; đó là thời điểm tốt cho phần nội dung trình bày bên dưới. Thời gian còn lại (Bước 1 và Bước 3-5) cần đối tác ngồi ở bàn phím: cấu hình thông tin đăng nhập, kiểm tra producer và Superset đã lên, khởi động vòng lặp refresh dbt, và đọc qua bảy câu truy vấn.

Nội dung trình bày

• Module này tồn tại để dựng một hệ nguồn đáng để migrate: một cột VARIANT, một CDC stream, hai scheduled task, và một lớp BI đọc trên toàn bộ những thứ đó — không phải một bảng đồ chơi. Mỗi thứ trong số đó sẽ trở thành một quyết định migration cụ thể ở module 02.
• Đi qua hình dạng Medallion một lượt trên sơ đồ: RAW -> STAGING -> ANALYTICS bên trong NYC_TAXI_DB, và hai đối tượng giữ cho nó vận hành độc lập với dbt — TRIPS_CDC_STREAM và hai scheduled task.
• Chỉ vào thư viện truy vấn (Bước 5) dù các đối tác sẽ chưa dịch các câu truy vấn cho tới module 02 — mỗi câu trong bảy câu đó đã có sẵn một comment phác ra phía ClickHouse, nên các đối tác có thể bắt đầu nhận diện mẫu (pattern) từ bây giờ.
• Nói thật rõ, và nhắc lại ở cuối module: hãy để producer và vòng lặp refresh dbt tiếp tục chạy. Bước cutover ở module 05 đo chính xác khoảng chênh lệch mà producer tạo ra giữa Snowflake và ClickHouse trong lúc migration, và một đối tác dọn dẹp cho gọn bằng cách dừng nó ở đây sẽ âm thầm phá hủy phần trình diễn đó ba module sau.

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

• terraform init thất bại với lỗi provider. Xác nhận Terraform >= 1.6 và máy có kết nối internet tới Terraform registry.
• snowsql báo connection refused. Kiểm tra SNOWFLAKE_ORG và SNOWFLAKE_ACCOUNT; thử trực tiếp bằng snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER}.
• dbt run thất bại với relation not found. Chạy ./setup.sh --skip-seed trước — nó tạo cấu trúc database — và xác nhận profiles.yml trỏ tới NYC_TAXI_DB.
• Superset báo connection refused. Superset cần khoảng 60 giây sau docker-compose up để khởi tạo; kiểm tra docker logs nyc_taxi_superset nếu nó vẫn chưa lên sau khoảng thời gian đó.
• Quá trình seed dữ liệu lâu hơn đối tác nghĩ. Lệnh insert TABLE(GENERATOR) sinh 50M dòng trong khoảng 10-12 phút; lệnh UPDATE tiếp theo để điền cột JSON TRIP_METADATA cho cả 50M dòng có thể mất thêm 15-20 phút nữa trên một warehouse SMALL. Đây là hành vi bình thường của Snowflake khi cập nhật một cột VARIANT lớn, không phải bị treo — hãy nói điều này trước khi một đối tác bắt đầu đi tìm lỗi trong một script đang chạy đúng.
• Một đối tác dừng producer sinh chuyến đi ngay khi module này trông như đã "xong." Nó chưa xong — module 02 tới module 05 đều phụ thuộc vào việc nó còn sống, và bước cutover của module 05 đo đúng khoảng chênh lệch mà nó tạo ra. Đây là sai lầm "dọn dẹp cho gọn" gây thiệt hại nhất trong cả workshop; hãy nói thẳng ra, nhiều hơn một lần.

Các bước reset

• Cấp phát lại mà không phải trả giá lần nạp dữ liệu ~10 phút: ./setup.sh --skip-seed (hạ tầng đã tồn tại và TRIPS_RAW đã có dữ liệu).
• Chỉ chỉnh sửa một thay đổi Terraform hoặc SQL: chỉ cần ./setup.sh --skip-seed.
• Chỉ chỉnh sửa các model dbt, bỏ qua hoàn toàn Superset: ./setup.sh --skip-seed --skip-superset.
• Thử các thay đổi Terraform mà không chạy lại dbt: thêm --skip-dbt.
• Sau khi thay đổi schema của một model dbt, buộc dựng lại toàn bộ phần incremental: --full-refresh (kết hợp với --skip-seed để không phải trả giá lần nạp dữ liệu lần nữa).
• Chỉ reset toàn bộ nếu môi trường không thể khôi phục: source .env && ./teardown.sh từ workshop_public/snowflake_migration_lab/01-setup-snowflake/, sau đó chạy lại ./setup.sh thuần. Cách này có tính phá hủy và phải trả lại toàn bộ ~10-12 phút seed — đừng dùng nó như phản ứng đầu tiên cho một đối tác đang bị mắc.