01 소스 환경

학습자 레슨 01 Source environment에 대응하는 진행자용 안내입니다.

타이밍

총 약 45분. Step 2(./setup.sh)만이 자동으로 진행되는 구간이며 — 대략 5-10분, 대부분은 TABLE(GENERATOR) 합성 데이터 시드입니다 — 조용히 지켜보기보다는 이야기를 얹을 만한 시간입니다. 아래 강의 흐름을 다루기에 좋은 순간입니다. 나머지 시간(Step 1과 Step 3-5)은 파트너가 키보드 앞에 있어야 합니다. 자격 증명 구성, 프로듀서와 Superset이 정상적으로 떴는지 확인, dbt 리프레시 루프 시작, 그리고 일곱 개의 쿼리 훑어보기입니다.

강의 흐름

• 이 모듈은 마이그레이션할 가치가 있는 소스를 만들기 위해 존재합니다. VARIANT 컬럼, CDC 스트림, 두 개의 스케줄된 태스크, 그리고 그 위에서 읽는 BI 계층 — 장난감 수준의 테이블이 아닙니다. 이들 각각은 모듈 02에서 구체적인 마이그레이션 결정 항목이 됩니다.
• 다이어그램에서 Medallion 구조를 한 번 짚어주세요. NYC_TAXI_DB 안의 RAW -> STAGING -> ANALYTICS, 그리고 dbt와 독립적으로 이를 계속 움직이게 하는 두 객체 — TRIPS_CDC_STREAM과 두 개의 스케줄된 태스크입니다.
• 파트너가 모듈 02까지는 쿼리를 변환하지 않겠지만 쿼리 라이브러리(Step 5)를 짚어주세요 — 일곱 개 각각에 ClickHouse 쪽을 스케치한 주석이 이미 달려 있어서, 파트너가 지금부터 패턴을 익히기 시작할 수 있습니다.
• 명확히 말하고 모듈 끝에서 한 번 더 반복하세요. 프로듀서와 dbt 리프레시 루프는 계속 실행 상태로 두어야 합니다. 모듈 05의 컷오버는 마이그레이션 중 프로듀서가 Snowflake와 ClickHouse 사이에 만들어낸 정확한 간격을 측정하는데, 여기서 정리하는 마음으로 이를 멈추는 파트너는 세 모듈 뒤의 그 시연을 조용히 망가뜨립니다.

흔한 실패 사례

• terraform init이 provider 오류로 실패합니다. Terraform >= 1.6인지, 그리고 해당 머신이 Terraform 레지스트리에 인터넷으로 접근할 수 있는지 확인하세요.
• snowsql 연결이 거부됩니다. SNOWFLAKE_ORG와 SNOWFLAKE_ACCOUNT를 확인하고, snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER}로 직접 시험하세요.
• dbt run이 relation not found로 실패합니다. 먼저 ./setup.sh --skip-seed를 실행하세요 — 데이터베이스 구조를 만들어 줍니다 — 그리고 profiles.yml이 NYC_TAXI_DB를 가리키는지 확인하세요.
• Superset이 connection refused를 표시합니다. Superset은 docker-compose up 이후 초기화에 약 60초가 필요합니다. 그 시간이 지나도 여전히 떠 있지 않으면 docker logs nyc_taxi_superset를 확인하세요.
• 데이터 시드가 파트너의 예상보다 오래 걸립니다. TABLE(GENERATOR) 삽입은 대략 10-12분에 5천만 행을 생성하며, 5천만 행 전체의 TRIP_METADATA JSON 컬럼을 채우는 후속 UPDATE는 SMALL 웨어하우스에서 15-20분을 더 추가할 수 있습니다. 이것은 큰 VARIANT 컬럼 업데이트에 대한 정상적인 Snowflake 동작이며 멈춘 것이 아닙니다 — 정상적으로 동작하는 스크립트를 파트너가 문제 해결하기 시작하기 전에 그렇다고 말해주세요.
• 이 모듈이 "끝난" 것처럼 보이면 파트너가 trip 프로듀서를 멈춥니다. 끝난 것이 아닙니다 — 모듈 02부터 05까지 모두 프로듀서가 살아 있는 데 의존하며, 특히 모듈 05의 컷오버는 프로듀서가 만들어낸 간격을 측정합니다. 이것은 워크숍 전체에서 가장 피해가 큰, 정리하려는 마음에서 나오는 실수입니다. 명시적으로, 두 번 이상 말하세요.

초기화 절차

• 약 10분짜리 데이터 로드를 다시 치르지 않고 재프로비저닝하기: ./setup.sh --skip-seed (인프라가 이미 존재하고 TRIPS_RAW에 이미 데이터가 있는 경우).
• Terraform 또는 SQL 변경만 반복 작업하기: ./setup.sh --skip-seed만 실행.
• Superset을 완전히 건너뛰고 dbt 모델만 반복 작업하기: ./setup.sh --skip-seed --skip-superset.
• dbt를 다시 실행하지 않고 Terraform 변경을 시험하기: --skip-dbt를 추가.
• dbt 모델 스키마를 변경한 뒤 증분 모델을 전체 재구축하도록 강제하기: --full-refresh (데이터 로드까지 다시 치르지 않도록 --skip-seed와 함께 사용).
• 환경을 복구할 수 없을 때만 전체 초기화: workshop_public/snowflake_migration_lab/01-setup-snowflake/에서 source .env && ./teardown.sh를 실행한 다음, 옵션 없는 ./setup.sh를 다시 실행합니다. 이것은 파괴적이며 약 10-12분의 전체 시드를 다시 치릅니다 — 막힌 파트너에 대한 첫 번째 대응으로 꺼내 들지 마세요.