03 Aprovisionamiento y migración

Complemento para 03 Aprovisionamiento y migración.

Tiempo

Unos 60 minutos en total, aunque importa más cómo se distribuyen que la cifra completa: aproximadamente 10–15 minutos de trabajo práctico —el Paso 1 aprovisiona el servicio de ClickHouse Cloud mediante Terraform en unos 2–3 minutos; el Paso 2 crea trips_raw, carga los datos de referencia de las zonas y ejecuta el primer dbt run todavía vacío en unos pocos minutos más—, seguidos de una transferencia de datos desatendida de entre 40 y 50 minutos. Durante el Paso 3 se mueven 50 millones de filas a una velocidad aproximada de 20 000 filas por segundo.

Este es el dato de planificación más importante de todo el taller: una vez iniciado el Paso 3, la sala no tiene nada que hacer durante buena parte de una hora. Ponlo en marcha y haz aquí la pausa, aprovecha la espera para recuperar el material del guion del módulo 02 que no cupo antes o celebra una sesión de preguntas en directo sobre las decisiones de migration-plan.md de los participantes. No programes una pausa en ningún otro punto de este módulo: resérvala expresamente para este momento.

Guion

• Explica el motivo que ofrece el propio módulo para mover los datos con un script de Python y no con un conector nativo: Snowflake no es un origen compatible con ClickPipes. Kafka, S3, Kinesis y la CDC de PostgreSQL/MySQL sí lo son, pero Snowflake no. Todas las alternativas —exportar a S3 o encadenar Snowflake -> Kafka -> ClickHouse— sustituyen una preparación a escala de laboratorio por infraestructura que no guarda relación directa con la migración: un bucket de S3, un rol de IAM o un clúster de Kafka.
• Conviene nombrar expresamente las ventajas reales del script de Python: no requiere una cuenta de AWS; es autocontenido, porque los dos paquetes nuevos viven en el mismo entorno virtual que dbt; puede reanudarse con --resume a partir de una marca de agua basada en max(pickup_at); y es lo bastante transparente como para que un participante lea el mapeo de columnas en vez de avanzar a ciegas por un asistente gráfico.
• Nombra honestamente la alternativa productiva: por encima de unos 500 M de filas o si importa el coste de recorrer toda la tabla con el warehouse, exportar a S3 es la opción más acertada: permite paralelizar tanto la exportación como la carga. El script de Python es adecuado para la escala del laboratorio, no una recomendación universal.
• Anticipa el desfase: el productor Snowflake sigue escribiendo durante el Paso 3, así que ClickHouse queda atrasado aproximadamente lo que dure la transferencia. Ese desfase es esperable en este punto y es exactamente lo que la transición del módulo 05 está diseñada para cerrar y medir. Explícalo antes de que alguien pregunte si la espera de 40–50 minutos está «perdiendo» datos.

Fallos habituales

• El primer dbt run del Paso 2 falla con Could not find profile named 'nyc_taxi_ch'. El laboratorio no crea automáticamente el perfil nyc_taxi_ch, aunque dbt_project.yml lo exige. La lección 03 Aprovisionamiento y migración explica este punto: la sección «Configura el perfil dbt» del Paso 2 muestra cómo incorporar un bloque nyc_taxi_ch: al ~/.dbt/profiles.yml existente antes de ejecutar dbt run. Si se omitió ese paso o se copió mal, remite al participante a él en vez de volver a explicar aquí la solución.
• Terraform falla con 401 Unauthorized. Verifica CLICKHOUSE_TOKEN_KEY y CLICKHOUSE_TOKEN_SECRET; ambas se encuentran en Settings -> API keys dentro de la interfaz de ClickHouse Cloud y deben tener alcance Admin.
• El script de migración falla a mitad de la ejecución. Repítelo con --resume; utiliza como marca de agua el max(pickup_at) ya presente en ClickHouse y omite las filas que ya se cargaron, por lo que reiniciarlo nunca deja una carga parcial e irrecuperable.
• El script ni siquiera conecta. Confirma todas las variables (echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD y echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD), después source .env && source .clickhouse_state y repite.
• dbt run falla con Connection refused o Unknown host. Falta CLICKHOUSE_HOST en la shell actual; ejecuta source .clickhouse_state desde workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ y vuelve a intentarlo.

Pasos de restablecimiento

• Si el script de migración se interrumpe, python scripts/02_migrate_trips.py --resume continúa desde la marca de agua en vez de reiniciar la transferencia completa de 50 millones de filas.
• Para reconstruir el servicio: source .env && ./teardown.sh desde workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ (destruye servicio y productor de ClickHouse si la transición ya se produjo), y después vuelve a ejecutar ./setup.sh. Esto no afecta al entorno de Snowflake del módulo 01, que tiene su propio teardown.sh en workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Un restablecimiento total resulta caro en este módulo: una migración nueva obliga a repetir los 40–50 minutos íntegros de transferencia. Siempre que el servicio de ClickHouse siga sano, prefiere --resume o una corrección dirigida a desmontarlo todo.