05 Benchmark y transición

Guía complementaria del facilitador para la lección del participante 05 Benchmark y transición.

Tiempo

Unos 45 minutos repartidos en cinco pasos: añadir los paneles de ClickHouse (Paso 1, un par de minutos mediante la importación automatizada), ejecutar el benchmark (Paso 2, siete consultas por tres ejecuciones y dos motores: unos minutos, casi sin intervención, pero lo bastante breve como para observarlo), realizar la transición (Paso 3, interactivo: detener el productor, recuperar el delta, actualizar dbt e iniciar el productor de ClickHouse, cada acción deliberadamente en ese orden), verificar la paridad (Paso 4, rápido) y desmontar los entornos (Paso 5).

TODO: el material propio del laboratorio no desglosa el tiempo de cada paso más allá de los 45 minutos totales del módulo. Confirma la distribución durante el ensayo, sobre todo si la pasada de recuperación --resume del Paso 3 es siempre lo bastante rápida (de segundos a minutos, según la propia descripción del laboratorio) como para no necesitar margen adicional.

Guion

• Este es el módulo que convierte «preparado» en «migrado». Los módulos 03 y 04 demostraron que los datos y la canalización funcionaban; este demuestra una cifra, la del benchmark, y que la ruta de escritura realmente cambia, mediante la transición.
• El orden de la transición constituye el contenido del módulo, no una formalidad: detén el productor de Snowflake, ejecuta --resume para cerrar el desfase, actualiza dbt y, por último, inicia el productor de ClickHouse. Cada paso depende del anterior; ejecutarlos en otro orden es precisamente lo que provoca un fallo silencioso de paridad (consulta Fallos habituales).
• Explica expresamente por qué --resume es rápido aquí, cuando la migración original del módulo 03 no lo fue: toma como marca de agua el max(pickup_at) ya presente en ClickHouse y solo recupera el delta. Por eso, un desfase abierto desde el módulo 01 se cierra en segundos o minutos, no con otra transferencia masiva de 40 a 50 minutos.
• Relaciona la transición con el estado vacío de agg_hourly_zone_trips en el módulo 04: se llena por primera vez en todo el laboratorio cuando arranca el productor de ClickHouse, porque su filtro solo coincidía con filas generadas en vivo. Esta es la respuesta a la pregunta que los participantes llevan planteando desde el módulo 04.
• Es el último módulo antes de la evaluación escrita. Recuerda al grupo que guarde migration-plan.md y el CSV del benchmark en un lugar accesible, porque el desmontaje del Paso 5 elimina ambos entornos cloud.

Fallos habituales

• Un participante importa manualmente el ZIP del panel desde la interfaz de Superset en vez de ejecutar add_clickhouse_connection.sh. En la exportación guardada, el host de ClickHouse se ha ocultado como your-instance.clickhouse.cloud. El script sustituye la URI con los datos de .env antes de importar; la importación manual conserva el host de ejemplo y no puede conectarse. Haz que el participante edite la conexión después para apuntar al CLICKHOUSE_HOST real y usar las credenciales correctas.
• Un participante omite la pasada de recuperación --resume del Paso 3 y realiza la transición de todos modos. ClickHouse pierde definitivamente todas las filas escritas en el desfase entre la migración original del módulo 03 y el momento en que se detuvo el productor: un fallo silencioso de paridad. La comprobación del Paso 4 está diseñada para detectarlo, pero solo si se ejecuta; quien pase directamente al informe del benchmark sin realizar el Paso 4 no verá las filas perdidas.
• Un participante muy ordenado ya detuvo el productor de Snowflake en el módulo 01 o 02. La transición no tiene ningún desfase que medir si el productor no se mantuvo activo. Esto invalida toda la demostración de la transición, no solo este paso. Si ha ocurrido, la solución honesta es reiniciar el productor, dejarlo escribir unos minutos para crear un desfase real y continuar. No existe forma de demostrar de manera retroactiva un desfase que nunca estuvo abierto.
• Falla la comprobación de paridad (diferencia superior al 0,01 %). Vuelve a ejecutar la pasada de recuperación y comprueba de nuevo: python scripts/02_migrate_trips.py --resume y después bash scripts/01_verify_migration.sh.
• Superset muestra 403 Forbidden. La cookie de sesión ha caducado. Cierra la sesión, vuelve a entrar en http://localhost:8088 y ejecuta de nuevo superset/add_clickhouse_connection.sh.
• El benchmark muestra N/A para una consulta, casi siempre Q7. El script del benchmark no pudo conectarse a ClickHouse. Confirma que CLICKHOUSE_HOST está definido (source .clickhouse_state) y que el servicio está en ejecución.

Pasos de restablecimiento

• Si falla la paridad, vuelve a ejecutar python scripts/02_migrate_trips.py --resume y después bash scripts/01_verify_migration.sh.
• Si es necesario deshacer la transición, es decir, realizar una transición inversa, ejecuta docker stop nyc_taxi_ch_producer y vuelve a iniciar el productor de Snowflake desde workshop_public/snowflake_migration_lab/01-setup-snowflake/superset con docker-compose --env-file ../.env up -d producer.
• Para restablecer por completo el entorno, source .env && ./teardown.sh, ejecutado desde workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/, destruye el servicio de ClickHouse Cloud y el contenedor del productor de ClickHouse, si ya se realizó la transición. Este script no toca Snowflake: desmóntalo por separado con source .env && ./teardown.sh desde workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Antes de ejecutar cualquiera de los dos desmontajes, confirma que migration-plan.md y el CSV del benchmark (scripts/benchmark_results_<timestamp>.csv) están guardados en un lugar accesible. Después desaparecen ambos entornos cloud, y el módulo 06 necesita exactamente esos dos archivos y ninguno más.