00 Preparación

Instala herramientas, crea dos cuentas cloud de prueba, clona el repositorio y construye ambos entornos virtuales dbt antes de tocar datos.

Punto de partida

Todavía no hay nada instalado. Necesitas un terminal y unos 30 minutos para instalar cinco herramientas de línea de comandos, crear dos cuentas cloud de prueba gratuitas, clonar el repositorio y construir dos entornos virtuales de Python.

Por qué

El taller provisiona dos nubes —Snowflake como fuente y ClickHouse Cloud como destino— y ejecuta dos adaptadores de dbt contra ellas, uno por nube. Ambos tienen requisitos mínimos estrictos de versión, y el que realmente puede causar problemas es Python: dbt-snowflake (y dbt-clickhouse, que se utilizará más adelante) requiere Python 3.11, 3.12 o 3.13. Python 3.14+ rompe mashumaro, una dependencia transitiva de la que dependen ambos adaptadores. Si te equivocas ahora, el fallo no aparece aquí: se manifiesta dos módulos después como un desconcertante error de importación de dbt que no parece tener relación alguna con la versión de Python. Fijar el intérprete en este módulo evita que se produzca ese problema.

Paso 1 — Instala las herramientas

Herramienta	Versión	Uso
Terraform	>= 1.6	Aprovisiona la infraestructura de Snowflake y ClickHouse Cloud
Docker Desktop	>= 24	Ejecuta el productor de viajes y Superset
Python	3.11–3.13	Scripts de migración, dbt y utilidades; consulta el aviso siguiente
dbt Core	>= 1.8	Canalizaciones Snowflake y ClickHouse
SnowSQL CLI	>= 1.2	Ejecuta SQL en Snowflake desde terminal

La versión de Python importa. dbt-snowflake y dbt-clickhouse requieren Python 3.11, 3.12 o 3.13. Python 3.14+ rompe la dependencia compartida mashumaro. Si el Python de tu sistema ya es 3.14+, instala 3.13 a su lado, por ejemplo con brew install python@3.13, en vez de sustituir la versión predeterminada. Precisamente por este motivo, el Paso 4 utiliza expresamente el intérprete python3.13.

Todos los paquetes que instales para este taller deben ir dentro de un entorno virtual aislado, nunca mediante un pip install global sin entorno. En el Paso 4 crearás los dos que necesitas.

Paso 2 — Crea las dos cuentas cloud

Necesitas una cuenta de prueba en cada nube; ambas son gratuitas y no requieren tarjeta de crédito:

Cuenta de prueba Snowflake: es el entorno de origen. El módulo 01 aprovisionará aquí un warehouse, una base de datos y una canalización Medallion.
Cuenta de prueba ClickHouse Cloud: es el entorno de destino. Permanecerá intacta hasta que el módulo 03 la aprovisione y la migración comience de verdad.

Crear ambas cuentas ahora evita que cualquiera de ellas se convierta en un bloqueo cuando empieces el módulo 01.

Paso 3 — Clona el repositorio

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

Todos los comandos del resto del taller dan por sentado que te encuentras en workshop_public/snowflake_migration_lab dentro de este repositorio clonado.

Paso 4 — Construye los dos entornos dbt

dbt-snowflake y dbt-clickhouse fijan intervalos de dependencias incompatibles, por lo que no pueden compartir un único entorno virtual. Construirás uno por adaptador, es decir, uno para cada nube de la migración.

dbt-snowflake, para la fuente en el Módulo 01:

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

dbt-clickhouse, para el destino desde el Módulo 03:

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

Cada .venv permanece dentro del directorio de su propio módulo. Activa el que necesites y ejecuta deactivate cuando cambies de uno a otro, en vez de intentar que un único entorno satisfaga los requisitos de ambos adaptadores.

Cómo verificar la finalización

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

Los cinco comandos deben mostrar una versión igual o superior al mínimo indicado, y cada dbt --version debe enumerar el adaptador que acabas de instalar en ese entorno virtual.

Estado final

Las herramientas están instaladas, ambas cuentas de prueba están activas, el repositorio está clonado y los dos entornos virtuales de dbt están construidos. Todavía no se ha aprovisionado nada en ninguna de las dos nubes; eso comienza en el módulo 01. Continúa con 01 Entorno de origen para construir el lado de Snowflake de la migración.