00 환경 설정

툴체인을 설치하고, 두 개의 클라우드 트라이얼 계정을 만들고, 리포지토리를 클론하고, 두 dbt 가상환경을 구축한다 — 데이터를 건드리기 전에 마이그레이션에 필요한 모든 것.

시작 지점

아직 아무것도 설치되지 않은 상태다. 터미널과 약 30분이 필요하다. 다섯 개의 명령줄 도구를 설치하고, 두 개의 무료 클라우드 트라이얼에 가입하고, 리포지토리를 클론하고, 두 개의 Python 가상환경을 구축한다.

이 워크샵은 두 개의 클라우드 — 소스로 Snowflake, 타깃으로 ClickHouse Cloud — 를 프로비저닝하고, 클라우드마다 하나씩 두 개의 dbt 어댑터를 실행한다. 두 어댑터 모두 엄격한 최소 버전 요구가 있고, 실제로 발목을 잡는 것은 Python이다. dbt-snowflake (그리고 뒤에서 쓰는 dbt-clickhouse)는 Python 3.11, 3.12, 또는 3.13을 요구한다. Python 3.14+는 두 어댑터가 공통으로 의존하는 전이 의존성 mashumaro를 깨뜨린다. 지금 이걸 잘못 맞추면 여기서 실패하지 않는다 — 두 모듈 뒤에, Python 버전과는 겉보기에 아무 관계 없어 보이는 혼란스러운 dbt import 오류로 나타난다. 이 모듈에서 인터프리터를 고정하는 것이 그 실패를 아예 발생하지 않게 만든다.

1단계 — 툴체인 설치

도구	버전	설치 목적
Terraform	>= 1.6	Snowflake와 ClickHouse Cloud 인프라를 프로비저닝한다
Docker Desktop	>= 24	트립 프로듀서와 Superset을 실행한다
Python	3.11–3.13	마이그레이션 스크립트, dbt, 유틸리티 스크립트 — 아래 콜아웃을 참고하라
dbt Core	>= 1.8	Snowflake와 ClickHouse 파이프라인
SnowSQL CLI	>= 1.2	터미널에서 Snowflake에 SQL을 실행한다

Python 버전이 중요하다. dbt-snowflake와 dbt-clickhouse는 모두 Python 3.11, 3.12, 또는 3.13을 요구한다. Python 3.14+는 두 어댑터가 공유하는 mashumaro 의존성을 깨뜨린다. 시스템 Python이 이미 3.14+라면 기본값을 교체하지 말고 3.13을 함께 설치하라(예: brew install python@3.13) — 아래 4단계가 정확히 이 이유로 python3.13 인터프리터를 명시적으로 사용한다.

이 워크샵을 위해 설치하는 모든 패키지는 격리된 virtualenv 안으로 들어가며, 전역 pip install을 그대로 쓰지 않는다 — 4단계에서 필요한 두 개를 만든다.

2단계 — 두 개의 클라우드 계정 생성

각 클라우드에 트라이얼 계정 하나가 필요하다. 둘 다 무료이고 신용카드가 필요 없다.

Snowflake 트라이얼 계정 — 소스 환경이다. 모듈 01에서 여기에 웨어하우스, 데이터베이스, Medallion 파이프라인을 프로비저닝한다.
ClickHouse Cloud 트라이얼 계정 — 타깃 환경이다. 모듈 03에서 프로비저닝하고 마이그레이션이 본격적으로 시작되기 전까지는 손대지 않는다.

지금 둘 다 가입해 두면 모듈 01을 시작할 때 어느 계정도 병목이 되지 않는다.

3단계 — 리포지토리 클론

git clone https://github.com/ClickHouse/ClickHouse_Demos.git
cd ClickHouse_Demos
cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

이후 이 워크샵의 모든 명령은 이 클론 안의 workshop_public/snowflake_migration_lab에 있다고 가정한다.

4단계 — 두 개의 dbt 가상환경 구축

dbt-snowflake와 dbt-clickhouse는 서로 충돌하는 의존성 범위를 고정하므로 하나의 virtualenv를 공유할 수 없다 — 어댑터마다 하나씩, 즉 마이그레이션의 클라우드 양쪽마다 하나씩 만든다.

모듈 01에서 소스에 대해 사용하는 dbt-snowflake:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/01-setup-snowflake"

# Use python3.13 explicitly if your system default is 3.14+
python3.13 -m venv .venv          # or: python3 -m venv .venv
source .venv/bin/activate
pip install "dbt-snowflake>=1.7,<2.0"
deactivate

모듈 03부터 타깃에 대해 사용하는 dbt-clickhouse:

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse"
python3.13 -m venv .venv
source .venv/bin/activate
pip install "dbt-clickhouse>=1.8,<2.0" snowflake-connector-python clickhouse-connect
deactivate

각 .venv는 자기 모듈 디렉터리 안에 머문다 — 하나의 환경이 두 어댑터를 모두 만족시키게 하려 애쓰지 말고, 필요한 쪽을 활성화하고 전환할 때 deactivate 하라.

완료 확인 방법

cd "$(git rev-parse --show-toplevel)/workshop_public/snowflake_migration_lab"

terraform version                  # expect >= 1.6
docker --version                   # expect >= 24
python3 --version                  # expect 3.11, 3.12, or 3.13
snowsql --version                  # expect >= 1.2

source 01-setup-snowflake/.venv/bin/activate
dbt --version                      # expect dbt-snowflake >= 1.7
deactivate

source 03-migrate-to-clickhouse/.venv/bin/activate
dbt --version                      # expect dbt-clickhouse >= 1.8
deactivate

다섯 개 명령 모두 표시된 최소 버전 이상을 출력해야 하고, 각 dbt --version은 해당 venv에 방금 설치한 어댑터를 나열해야 한다.

종료 상태

툴체인이 설치되고, 두 트라이얼 계정이 살아 있고, 리포지토리가 클론되고, 두 dbt 가상환경이 구축되었다. 어느 클라우드에도 아직 프로비저닝된 것은 없다 — 그것은 모듈 01에서 시작한다. 마이그레이션의 Snowflake 쪽을 구축하려면 01 소스 환경으로 계속 진행하라.