00 Preparação

Material de apoio ao instrutor para a aula do participante 00 Preparação.

Duração

Cerca de 30 minutos no total. Este é um trabalho prévio, não conteúdo para o dia da sessão: envie-o aos parceiros com antecedência e confirme a conclusão no dia anterior, não na mesma manhã. Nada aqui é autônomo no sentido de “iniciar e ir embora”; são cinco instalações de ferramentas, dois cadastros de conta, uma clonagem e a criação de dois ambientes virtuais, tudo exigindo que o parceiro permaneça diante do teclado. Um parceiro que chega sem ter feito essa preparação consome aproximadamente 30 minutos da sessão para recuperar o atraso ao vivo, sacrificando o conteúdo que o módulo 01 deveria cobrir nesse intervalo.

Roteiro

• Apresente este módulo como infraestrutura básica, não como conteúdo: duas nuvens (Snowflake como origem e ClickHouse Cloud como destino), dois adaptadores dbt, um para cada nuvem, e o mesmo requisito mínimo rígido de Python para ambos.
• Há um fato que vale repetir em voz alta: dbt-snowflake e dbt-clickhouse exigem Python 3.11, 3.12 ou 3.13. O Python 3.14 ou mais recente quebra uma dependência transitiva compartilhada, mashumaro, nos dois adaptadores.
• Mostre os dois ambientes virtuais separados — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv e workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — e explique por que eles não podem ser combinados: os adaptadores fixam intervalos de dependências incompatíveis.
• Incentive a criação das duas contas de nuvem agora, e não no dia da sessão: nem a avaliação do Snowflake nem a do ClickHouse Cloud deve se tornar um impedimento quando o módulo 01 começar.

Falhas comuns

• O Python 3.14 ou mais recente quebra dbt-snowflake e dbt-clickhouse por causa de mashumaro. Esta é a principal falha do módulo e a mais perigosa, porque fixar o interpretador incorreto não provoca erro aqui: o problema só aparece dois módulos depois, como um erro confuso de importação do dbt que não parece ter relação com a versão do Python. Confirme que python3 --version informa 3.11, 3.12 ou 3.13 para o interpretador realmente usado por cada ambiente virtual — workshop_public/snowflake_migration_lab/01-setup-snowflake/.venv e workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/.venv — e não apenas para o padrão do sistema, antes de aprovar a conclusão deste módulo pelo parceiro.
• PENDENTE: nenhum outro modo de falha deste módulo está documentado no README do próprio laboratório. Registre aqui qualquer outro problema observado no ensaio (proxy ou firewall corporativo bloqueando pip install ou terraform init, avisos de licença do Docker Desktop na primeira execução, demora na aprovação das contas de avaliação).

Etapas de redefinição

• Versão incorreta do Python por trás de um ambiente virtual: use cd para entrar no diretório do ambiente do módulo afetado — workshop_public/snowflake_migration_lab/01-setup-snowflake/ ou workshop_public/snowflake_migration_lab/03-migrate-to-clickhouse/ —, exclua-o e reconstrua-o com o interpretador fixado, por exemplo rm -rf .venv && python3.13 -m venv .venv && source .venv/bin/activate, e reinstale o adaptador desse ambiente como mostrado na etapa 4 da página do participante.
• Nenhum script de desmontagem se aplica a este módulo, pois ainda não há recursos provisionados em nenhuma das nuvens. Se um parceiro precisar repetir uma etapa, é mais barato executá-la novamente do que redefinir qualquer coisa.
• PENDENTE: confirme durante o ensaio se vale a pena distribuir antecipadamente um ambiente virtual já criado para uma sala com Wi-Fi instável, em vez de instalar ao vivo cinco ferramentas e dois ambientes virtuais no dia.