03 Provisionamento e migração

Material de apoio ao instrutor para a aula do participante 03 Provisionamento e migração.

Duração

Cerca de 60 minutos no total, sendo que a distribuição do tempo importa mais do que o total: aproximadamente 10 a 15 minutos de trabalho prático (a etapa 1 provisiona o serviço ClickHouse Cloud com Terraform, em cerca de 2 a 3 minutos; a etapa 2 cria trips_raw, carrega os dados de referência das zonas e executa o primeiro dbt run vazio, em mais alguns minutos), seguidos de 40 a 50 minutos de transferência autônoma dos dados (o script de migração da etapa 3 move 50 milhões de linhas a aproximadamente 20 mil linhas/s).

Este é o fato de cronograma mais importante de todo o workshop: depois que a etapa 3 começa, a turma não tem nada a fazer durante boa parte de uma hora. Inicie-a e faça o intervalo aqui, use a espera para o roteiro do módulo 02 que a turma não teve tempo de ver ou faça uma sessão de perguntas e respostas ao vivo sobre as decisões registradas no migration-plan.md dos parceiros. Não planeje um intervalo em nenhum outro ponto deste módulo; faça-o aqui, de propósito.

Roteiro

• Explique o motivo apresentado pelo próprio módulo para mover os dados com um script Python, e não com um conector nativo: o Snowflake não é uma origem aceita pelo ClickPipes (Kafka, S3, Kinesis e CDC de Postgres/MySQL são; Snowflake não), e todas as alternativas (exportação para S3 ou Snowflake -> Kafka -> ClickHouse) trocam uma configuração na escala do laboratório por uma infraestrutura que nada tem a ver com a migração em si — um bucket S3, uma função do IAM ou um cluster Kafka.
• Destaque os verdadeiros benefícios do script Python: dispensa uma conta AWS, é autocontido (os dois novos pacotes ficam no mesmo ambiente virtual do dbt), pode ser retomado com --resume a partir de uma marca d'água max(pickup_at) e é transparente o bastante para que um parceiro leia o mapeamento de colunas em vez de percorrer um assistente na interface.
• Apresente com honestidade a alternativa de produção: acima de aproximadamente 500 milhões de linhas, ou quando o custo de um warehouse que analisa a tabela inteira for relevante, exportar para S3 é a melhor escolha — exportação paralela e carga paralela. O script Python é adequado à escala do laboratório, não uma recomendação universal.
• Antecipe agora a lacuna da migração, embora ela só seja fechada no módulo 05: o produtor do Snowflake continua gravando durante toda a etapa 3, portanto o ClickHouse fica atrás do Snowflake por aproximadamente o tempo da transferência. Essa lacuna é esperada aqui e é exatamente o que a virada do módulo 05 foi projetada para fechar e medir. Explique isso antes que alguém pergunte se a espera de 40 a 50 minutos está “perdendo” dados.

Falhas comuns

• O primeiro dbt run da etapa 2 falha com Could not find profile named 'nyc_taxi_ch'. Nada no laboratório cria automaticamente o perfil dbt nyc_taxi_ch do ClickHouse, embora dbt_project.yml o exija. A aula do participante 03 Provisionamento e migração aborda o problema: em “Configure o perfil dbt”, na etapa 2, o parceiro adiciona um bloco nyc_taxi_ch: ao ~/.dbt/profiles.yml existente antes da execução deste dbt run. Se ele ignorou ou copiou incorretamente essa etapa, encaminhe-o de volta a ela em vez de explicar novamente a solução aqui.
• A autenticação do Terraform falha com 401 Unauthorized. Verifique CLICKHOUSE_TOKEN_KEY e CLICKHOUSE_TOKEN_SECRET: ambos ficam na interface do ClickHouse Cloud, em Settings -> API keys, e devem ter escopo Admin.
• O script de migração falha no meio da execução. Execute-o novamente com --resume; ele usa como marca d'água o max(pickup_at) já presente no ClickHouse e ignora as linhas carregadas, portanto um reinício nunca gera uma carga parcial impossível de recuperar.
• O script de migração não consegue se conectar. Confirme que todas as variáveis de ambiente do Snowflake e do ClickHouse estão definidas (echo $SNOWFLAKE_ORG $SNOWFLAKE_ACCOUNT $SNOWFLAKE_USER $SNOWFLAKE_PASSWORD e echo $CLICKHOUSE_HOST $CLICKHOUSE_PASSWORD), execute source .env && source .clickhouse_state e tente novamente.
• dbt run falha com Connection refused ou Unknown host. CLICKHOUSE_HOST não está definido no shell atual. Execute source .clickhouse_state em workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ e tente novamente.

Etapas de redefinição

• Script de migração interrompido: python scripts/02_migrate_trips.py --resume continua a partir da marca d'água, sem reiniciar toda a transferência de 50 milhões de linhas.
• Se o serviço ClickHouse Cloud precisar de uma reconstrução limpa: execute source .env && ./teardown.sh em workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ (isso destrói o serviço e o contêiner do produtor do ClickHouse, caso a virada já tenha ocorrido) e depois execute ./setup.sh novamente. Isso não afeta o lado Snowflake do módulo 01, que tem seu próprio teardown.sh em workshop_public/snowflake_migration_lab/01-setup-snowflake/.
• Uma redefinição completa é cara aqui: uma nova migração repete toda a transferência de 40 a 50 minutos. Prefira --resume ou uma correção pontual à desmontagem completa sempre que o próprio serviço ClickHouse continuar íntegro.