03 프로비저닝과 마이그레이션

학습자 레슨 03 Provision and migrate에 대응하는 진행자용 안내입니다.

타이밍

총 약 60분이며, 총합보다 그 구성이 더 중요합니다. 손으로 하는 작업이 대략 10-15분 (Step 1은 Terraform으로 ClickHouse Cloud 서비스를 프로비저닝, 약 2-3분. Step 2는 trips_raw를 만들고 zone 참조 데이터를 시드하고 첫 번째 빈 dbt run을 실행, 몇 분 더), 그 뒤에 40-50분간 대기만 하는 데이터 전송(Step 3의 마이그레이션 스크립트가 초당 약 2만 행 속도로 5천만 행을 이동)이 이어집니다.

이것이 워크숍 전체에서 가장 중요한 일정 관련 사실입니다. Step 3이 시작되면 거의 한 시간 동안 강의실이 할 일이 없습니다. 이를 시작한 다음, 여기서 휴식을 가지거나, 강의실이 다룰 시간이 없었던 모듈 02의 강의 흐름 자료에 이 대기 시간을 쓰거나, 파트너들의 migration-plan.md 결정에 대한 라이브 Q&A를 하세요. 이 모듈의 다른 어느 지점에도 휴식을 배치하지 마세요 — 의도적으로 여기에 배치하세요.

강의 흐름

• 이 랩이 네이티브 커넥터가 아니라 Python 스크립트로 데이터를 옮기는 이유에 대한 모듈 자체의 근거: Snowflake는 지원되는 ClickPipes 소스가 아니며(Kafka, S3, Kinesis, 그리고 Postgres/MySQL CDC는 지원되지만 Snowflake는 아닙니다), 모든 대안(S3 익스포트, Snowflake -> Kafka -> ClickHouse)은 랩 규모의 설정을 마이그레이션 자체와는 아무 상관 없는 인프라 — S3 버킷, IAM 역할, Kafka 클러스터 — 와 맞바꿉니다.
• Python 스크립트의 실제 장점으로 명시할 만한 것들: AWS 계정이 필요 없고, 자기 완결적이며 (새로 추가되는 두 패키지가 dbt와 같은 venv에 들어갑니다), max(pickup_at) 워터마크에 대해 --resume으로 재개할 수 있고, 파트너가 UI 위저드를 클릭해 나가는 대신 컬럼 매핑을 직접 읽을 수 있을 만큼 투명합니다.
• 프로덕션 대안을 솔직하게 언급하세요. 대략 5억 행을 넘어가거나 전체 테이블 스캔에 따르는 웨어하우스 비용이 문제가 되는 경우에는 S3 익스포트가 더 나은 선택입니다 — 병렬 익스포트, 병렬 로드. Python 스크립트는 랩 규모에 맞는 선택이지 보편적인 권장안이 아닙니다.
• 모듈 05가 이를 닫더라도 마이그레이션 간격을 지금 미리 짚어주세요. Step 3이 실행되는 동안 Snowflake 프로듀서가 계속 쓰기 때문에 ClickHouse는 대략 전송 시간만큼 Snowflake보다 뒤처집니다. 그 간격은 여기서 예상된 것이며, 모듈 05의 컷오버가 바로 그것을 닫고 측정하기 위해 만들어졌습니다 — 40-50분의 대기가 데이터를 "낭비"하는 것 아니냐고 누가 묻기 전에 이렇게 말해주세요.

흔한 실패 사례

• Step 2의 첫 dbt run이 Could not find profile named 'nyc_taxi_ch'로 실패합니다. dbt_project.yml이 요구하지만, 랩의 어떤 부분도 ClickHouse nyc_taxi_ch dbt 프로필을 자동으로 만들지 않습니다. 학습자 레슨 03 Provision and migrate가 이를 다룹니다. Step 2의 "Configure the dbt profile"이 이 dbt run을 실행하기 전에 기존 ~/.dbt/profiles.yml에 nyc_taxi_ch: 블록을 병합하도록 파트너를 안내합니다. 파트너가 그 단계를 건너뛰거나 잘못 복사했다면, 여기서 우회 방법을 다시 설명하지 말고 그 단계로 돌려보내세요.
• Terraform 인증이 401 Unauthorized로 실패합니다. CLICKHOUSE_TOKEN_KEY와 CLICKHOUSE_TOKEN_SECRET을 확인하세요 — 둘 다 ClickHouse Cloud UI의 Settings -> API keys 아래에 있으며 Admin 스코프를 가지고 있어야 합니다.
• 마이그레이션 스크립트가 실행 중간에 실패합니다. --resume으로 다시 실행하세요. 이미 ClickHouse에 있는 max(pickup_at)을 워터마크로 삼아 이미 로드된 행을 건너뛰므로, 재시작이 부분적이고 복구 불가능한 로드를 만들어내는 일은 없습니다.
• 마이그레이션 스크립트가 아예 접속하지 못합니다. 모든 Snowflake 및 ClickHouse 환경 변수가 설정되어 있는지 확인하고(echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD와 echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD), source .env && source .clickhouse_state 후 재시도하세요.
• dbt run이 Connection refused 또는 Unknown host로 실패합니다. 현재 셸에 CLICKHOUSE_HOST가 설정되지 않은 것입니다 — workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/에서 source .clickhouse_state를 실행하고 재시도하세요.

초기화 절차

• 마이그레이션 스크립트가 중단된 경우: python scripts/02_migrate_trips.py --resume은 5천만 행 전송을 처음부터 다시 하지 않고 워터마크부터 이어갑니다.
• ClickHouse Cloud 서비스를 깨끗하게 재구축해야 하는 경우: workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/에서 source .env && ./teardown.sh(서비스와, 컷오버가 이미 일어났다면 ClickHouse 프로듀서 컨테이너까지 파괴)를 실행한 다음 ./setup.sh를 다시 실행하세요. 이것은 모듈 01의 Snowflake 쪽은 건드리지 않습니다 — 그쪽은 workshop_public/snowflake_migration_lab/01-setup-snowflake/에 자체 teardown.sh를 가지고 있습니다.
• 여기서 전체 초기화는 비용이 큽니다. 새로 마이그레이션하면 40-50분 전송을 전부 다시 치릅니다. ClickHouse 서비스 자체가 아직 건강한 상황이라면 전체 teardown보다 --resume 이나 국소적인 수정을 택하세요.