01 Ambiente de origem

Material de apoio ao instrutor para a aula do participante 01 Ambiente de origem.

Duração

Cerca de 45 minutos no total. A etapa 2 (./setup.sh) é o único trecho autônomo — aproximadamente 5 a 10 minutos, em sua maioria para a carga sintética de dados com TABLE(GENERATOR) — e vale a pena usar esse tempo para explicar o roteiro abaixo em vez de assistir em silêncio. No restante (etapas 1 e 3 a 5), o parceiro precisa permanecer no teclado: configurar credenciais, verificar se o produtor e o Superset estão ativos, iniciar o ciclo de atualização do dbt e conhecer as sete consultas.

Roteiro

• Este módulo existe para criar uma origem que valha a pena migrar: uma coluna VARIANT, um stream CDC, duas tarefas agendadas e uma camada de BI que consulta tudo isso — não uma tabela de brinquedo. Cada um desses elementos se transforma em uma decisão específica de migração no módulo 02.
• Percorra uma vez o formato Medallion no diagrama: RAW -> STAGING -> ANALYTICS dentro de NYC_TAXI_DB, além dos dois objetos que o mantêm em movimento independentemente do dbt: TRIPS_CDC_STREAM e as duas tarefas agendadas.
• Mostre a biblioteca de consultas (etapa 5), embora os parceiros só façam a tradução no módulo 02. Cada uma das sete consultas já contém um comentário que esboça a alternativa no ClickHouse, permitindo que os parceiros comecem a reconhecer os padrões.
• Diga com clareza e repita ao final do módulo: mantenha o produtor e o ciclo de atualização do dbt em execução. A virada do módulo 05 mede exatamente a diferença que o produtor cria entre Snowflake e ClickHouse durante a migração. Um parceiro que “organiza” o ambiente e o interrompe aqui destrói silenciosamente essa demonstração três módulos depois.

Falhas comuns

• terraform init falha com um erro de provedor. Confirme que o Terraform é da versão 1.6 ou superior e que a máquina consegue acessar o registro do Terraform pela internet.
• Conexão recusada no snowsql. Verifique SNOWFLAKE_ORG e SNOWFLAKE_ACCOUNT; teste diretamente com snowsql -a ${SNOWFLAKE_ORG}-${SNOWFLAKE_ACCOUNT} -u ${SNOWFLAKE_USER}.
• dbt run falha com relation not found. Execute primeiro ./setup.sh --skip-seed, que cria a estrutura do banco de dados, e confirme que profiles.yml aponta para NYC_TAXI_DB.
• O Superset mostra connection refused. O Superset precisa de cerca de 60 segundos após docker-compose up para ser inicializado; consulte docker logs nyc_taxi_superset se ele ainda estiver indisponível depois desse período.
• A carga de dados demora mais do que o parceiro esperava. A inserção com TABLE(GENERATOR) gera 50 milhões de linhas em cerca de 10 a 12 minutos; o UPDATE subsequente que preenche a coluna JSON TRIP_METADATA em todas as 50 milhões de linhas pode acrescentar outros 15 a 20 minutos em um warehouse SMALL. Esse é o comportamento normal do Snowflake ao atualizar uma coluna VARIANT grande, não uma paralisação. Avise antes que o parceiro comece a diagnosticar um script que está funcionando corretamente.
• Um parceiro interrompe o produtor de corridas quando este módulo parece “concluído”. Ele não está: todos os módulos de 02 a 05 dependem de sua execução, e a virada do módulo 05 mede especificamente a diferença criada por ele. Este é o erro de organização mais prejudicial de todo o workshop; deixe isso explícito, mais de uma vez.

Etapas de redefinição

• Para provisionar novamente sem pagar outra vez pelos cerca de 10 minutos da carga de dados: ./setup.sh --skip-seed (a infraestrutura já existe e TRIPS_RAW já contém dados).
• Para iterar apenas em uma alteração de Terraform ou SQL: somente ./setup.sh --skip-seed.
• Para iterar apenas nos modelos dbt e ignorar inteiramente o Superset: ./setup.sh --skip-seed --skip-superset.
• Para testar alterações do Terraform sem executar o dbt novamente: acrescente --skip-dbt.
• Depois de alterar o esquema de um modelo dbt, force uma reconstrução incremental completa: --full-refresh (combine com --skip-seed para não repetir também a carga de dados).
• Faça uma redefinição completa somente se o ambiente não puder ser recuperado: execute source .env && ./teardown.sh em workshop_public/snowflake_migration_lab/01-setup-snowflake/ e depois execute novamente ./setup.sh sem opções. A operação é destrutiva e repete toda a carga de cerca de 10 a 12 minutos; não a use como primeira resposta a um parceiro bloqueado.