03 Cấp phát và di chuyển dữ liệu

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 03 Cấp phát và di chuyển dữ liệu.

Thời lượng

Khoảng 60 phút, và cách thời gian đó phân bố quan trọng hơn con số tổng: khoảng 10-15 phút làm việc trực tiếp (Bước 1 cấp phát service ClickHouse Cloud qua Terraform, khoảng 2-3 phút; Bước 2 tạo trips_raw, seed dữ liệu tham chiếu về zone, và chạy lần dbt run rỗng đầu tiên, thêm vài phút nữa) rồi tới 40-50 phút truyền dữ liệu tự chạy (script migration ở Bước 3, chuyển 50 triệu dòng với tốc độ khoảng 20K dòng/giây).

Đây là yếu tố quan trọng nhất về xếp thời gian trong cả workshop: khi Bước 3 đã bắt đầu, lớp học không có gì để làm trong gần suốt một giờ. Hãy khởi động nó, rồi nghỉ ở đây, hoặc dùng khoảng chờ đó cho phần nội dung trình bày của module 02 mà lớp chưa đủ thời gian nói, hoặc một phiên Q&A trực tiếp về các quyết định trong migration-plan.md của các đối tác. Đừng xếp giờ nghỉ ở bất kỳ chỗ nào khác trong module này — hãy xếp nó ở đây, một cách có chủ đích.

Nội dung trình bày

• Lý do của chính module này về việc vì sao lab chuyển dữ liệu bằng một script Python thay vì một connector native: Snowflake không phải là nguồn được ClickPipes hỗ trợ (Kafka, S3, Kinesis và CDC từ Postgres/MySQL thì có; Snowflake thì không), và mọi phương án khác (export qua S3, Snowflake -> Kafka -> ClickHouse) đều đánh đổi một thiết lập ở quy mô lab để lấy hạ tầng chẳng liên quan gì tới bản thân việc migration — một S3 bucket, một IAM role, một cluster Kafka.
• Những điểm mạnh thực sự của script Python, đáng nêu rõ: không cần tài khoản AWS, tự chứa (cả hai package mới đều nằm trong cùng venv với dbt), có thể tiếp tục lại bằng --resume dựa trên watermark max(pickup_at), và minh bạch đủ để một đối tác có thể đọc phần mapping cột thay vì click qua một wizard trên UI.
• Nói thẳng về phương án dành cho production: vượt quá khoảng 500M dòng, hoặc ở những nơi chi phí quét toàn bảng của warehouse là đáng kể, export qua S3 là lựa chọn tốt hơn — export song song, load song song. Script Python là đúng cho quy mô lab, không phải một khuyến nghị phổ quát.
• Giới thiệu trước về khoảng chênh lệch dữ liệu (migration gap) ngay bây giờ, dù module 05 mới là nơi đóng nó lại: producer trên Snowflake vẫn ghi liên tục suốt thời gian Bước 3 chạy, nên ClickHouse bị tụt lại sau Snowflake khoảng bằng đúng độ dài của quá trình truyền. Khoảng chênh lệch đó là điều được dự kiến ở đây, và nó chính là thứ mà bước cutover ở module 05 được thiết kế để đóng lại và đo — hãy nói điều này trước khi có người hỏi liệu 40-50 phút chờ đợi kia có đang "làm mất" dữ liệu hay không.

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

• Lần dbt run đầu tiên ở Bước 2 thất bại với Could not find profile named 'nyc_taxi_ch'. Không có gì trong lab tự động tạo profile dbt nyc_taxi_ch cho ClickHouse, dù dbt_project.yml yêu cầu nó. Bài học của học viên 03 Cấp phát và di chuyển dữ liệu có đề cập chuyện này: mục "Configure the dbt profile" ở Bước 2 hướng dẫn các đối tác gộp một khối nyc_taxi_ch: vào ~/.dbt/profiles.yml hiện có của họ trước khi lần dbt run này chạy. Nếu một đối tác bỏ qua hoặc sao chép sai bước đó, hãy chỉ họ quay lại đó thay vì giải thích lại cách xử lý ở đây.
• Xác thực Terraform thất bại với 401 Unauthorized. Kiểm tra CLICKHOUSE_TOKEN_KEY và CLICKHOUSE_TOKEN_SECRET — cả hai đều nằm trong ClickHouse Cloud UI tại Settings -> API keys và phải có phạm vi Admin.
• Script migration thất bại giữa lúc đang chạy. Chạy lại với --resume; nó đã watermark theo max(pickup_at) hiện có trong ClickHouse và bỏ qua những dòng đã load, nên việc khởi động lại không bao giờ tạo ra một lần load dở dang không thể khôi phục.
• Script migration không kết nối được ngay từ đầu. Xác nhận mọi biến môi trường của Snowflake và ClickHouse đều đã được đặt (echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD và echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD), rồi source .env && source .clickhouse_state và thử lại.
• dbt run thất bại với Connection refused hoặc Unknown host. CLICKHOUSE_HOST chưa được đặt trong shell hiện tại — chạy source .clickhouse_state từ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ và thử lại.

Các bước reset

• Script migration bị ngắt giữa lúc chạy: python scripts/02_migrate_trips.py --resume tiếp tục từ watermark thay vì chạy lại toàn bộ quá trình truyền 50M dòng.
• Service ClickHouse Cloud cần được dựng lại sạch: source .env && ./teardown.sh từ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ (phá hủy service và container producer ClickHouse nếu cutover đã diễn ra), sau đó chạy lại ./setup.sh. Cách này không ảnh hưởng tới phía Snowflake của module 01 — phía đó có teardown.sh riêng trong workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Reset toàn bộ ở đây rất đắt: một lần migration mới phải trả lại toàn bộ 40-50 phút truyền dữ liệu. Hãy ưu tiên --resume hoặc một cách sửa có mục tiêu hơn là teardown toàn bộ, miễn là bản thân service ClickHouse vẫn còn khỏe.