00 การติดตั้ง

คู่มือประกอบสำหรับผู้สอนของบทเรียนผู้เรียน 00 การติดตั้ง

การจัดเวลา

รวมประมาณ 30 นาที นี่เป็นงานเตรียมล่วงหน้า ไม่ใช่เนื้อหาของวันจัดเวิร์กช็อป — ส่งให้พาร์ตเนอร์ ก่อนวันเวิร์กช็อปและยืนยันว่าทำเสร็จในวันก่อนหน้า ไม่ใช่เช้าวันนั้น ไม่มีอะไรที่นี่ที่รันเองได้ ในความหมายของ "สั่งรันแล้วเดินจากไป" มันคือการติดตั้งเครื่องมือห้าตัว การสมัครบัญชีสองบัญชี การ clone หนึ่งครั้ง และการสร้าง virtualenv สองชุด ซึ่งทั้งหมดต้องมีมือของพาร์ตเนอร์ อยู่บนคีย์บอร์ดตลอดเวลา พาร์ตเนอร์ที่มาถึงโดยข้ามโมดูลนี้จะทำให้เสียเวลาในเวิร์กช็อปไปราว 30 นาทีเพื่อตามให้ทันแบบสด โดยแลกมาด้วยสิ่งที่โมดูล 01 ควรจะครอบคลุมในช่วงเวลานั้น

แนวการบรรยาย

• วางกรอบโมดูลนี้ว่าเป็นงานระบบพื้นฐาน ไม่ใช่เนื้อหา: สองคลาวด์ (Snowflake เป็นต้นทาง และ ClickHouse Cloud เป็นเป้าหมาย) สอง dbt adapter หนึ่งตัวต่อหนึ่งคลาวด์ และทั้งสอง adapter ใช้ข้อกำหนดขั้นต่ำของ Python เดียวกันอย่างเข้มงวด
• ข้อเท็จจริงหนึ่งเดียวที่ควรพูดออกมาให้ชัด และพูดมากกว่าหนึ่งครั้ง: ทั้ง dbt-snowflake และ dbt-clickhouse ต้องใช้ Python 3.11, 3.12 หรือ 3.13 ส่วน Python 3.14+ ทำให้ dependency ที่ส่งต่อกันมาร่วมกันตัวหนึ่งคือ mashumaro เสียในทั้งสอง adapter
• ชี้ให้เห็น virtualenv สองชุดที่แยกกัน — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv และ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — และอธิบายว่าเหตุใด จึงรวมเป็นชุดเดียวไม่ได้: สอง adapter ตรึงช่วงเวอร์ชันของ dependency ที่ขัดกัน
• กระตุ้นให้สมัครทั้งสองคลาวด์ตั้งแต่ตอนนี้ ไม่ใช่ในวันจัดเวิร์กช็อป: ทั้งบัญชีทดลอง Snowflake และบัญชีทดลอง ClickHouse Cloud ไม่ควรกลายเป็นตัวขวางเมื่อโมดูล 01 เริ่มแล้ว

ปัญหาที่พบบ่อย

• Python 3.14+ ทำให้ dbt-snowflake และ dbt-clickhouse เสียผ่าน mashumaro นี่คือ ปัญหาหลักของโมดูลนี้ และเป็นปัญหาที่อันตรายที่สุด เพราะการตรึงตัวแปลภาษาผิดจะไม่แสดง ความผิดพลาดที่นี่ — มันจะปรากฏขึ้นสองโมดูลถัดไปในรูปของข้อผิดพลาดการ import ของ dbt ที่สับสน ซึ่งดูไม่มีความเกี่ยวข้องชัดเจนกับเวอร์ชันของ Python เลย ยืนยันว่า python3 --version รายงาน 3.11, 3.12 หรือ 3.13 สำหรับตัวแปลภาษาที่อยู่ เบื้องหลัง virtualenv แต่ละชุดจริง ๆ — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv และ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — ไม่ใช่เพียง ค่าเริ่มต้นของระบบ — ก่อนที่จะเซ็นรับรองว่าพาร์ตเนอร์ผ่านโมดูลนี้
• TODO: ไม่มีรูปแบบความผิดพลาดอื่นของโมดูลนี้ที่ถูกบันทึกไว้ใน README ของแล็บเอง บันทึกสิ่งอื่นที่สังเกตพบระหว่างการซ้อมไว้ที่นี่ (พร็อกซีหรือไฟร์วอลล์ขององค์กรที่ขวาง pip install หรือ terraform init การแจ้งเรื่องสัญญาอนุญาตของ Docker Desktop เมื่อเปิดครั้งแรก ความล่าช้าในการอนุมัติการสมัครบัญชีทดลอง)

ขั้นตอนการรีเซ็ต

• เวอร์ชัน Python เบื้องหลัง venv ผิด: cd เข้าไปใน virtualenv ของโมดูลที่ผิด — workshop_public/snowflake_migration_lab/01-setup-snowflake/ หรือ workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ — แล้วลบและ สร้างใหม่โดยใช้ตัวแปลภาษาที่ตรึงไว้ ตัวอย่างเช่น rm -rf .venv && python3.13 -m venv .venv && source .venv/bin/activate และติดตั้ง adapter ของ venv นั้นใหม่ตามที่แสดง ไว้ในขั้นตอนที่ 4 ของหน้าผู้เรียน
• ไม่มีสคริปต์รื้อถอนที่ใช้กับโมดูลนี้ — ยังไม่มีการจัดเตรียมสิ่งใดในคลาวด์ทั้งสอง หากพาร์ตเนอร์ต้องทำขั้นตอนใดซ้ำ การรันขั้นตอนนั้นใหม่ประหยัดกว่าการรีเซ็ต อะไรทั้งนั้น
• TODO: ยืนยันระหว่างการซ้อมว่าการแจก venv ที่สร้างไว้ล่วงหน้าคุ้มค่าหรือไม่สำหรับห้องที่ Wi-Fi ไม่เสถียร แทนที่จะติดตั้งเครื่องมือห้าตัวและ venv สองชุดแบบสดในวันจัดเวิร์กช็อป