02 Planejamento e projeto

Material de apoio ao instrutor para a aula do participante 02 Planejamento e projeto.

Duração

Cerca de 90 minutos, quase nada deles em execução autônoma. Este é o único módulo baseado em trabalho individual ou em duplas nas planilhas, e não em scripts executados em segundo plano. A etapa 1 (o script de criação de perfil) é a única parte automatizada e termina em poucos minutos; todo o restante — as cinco planilhas da etapa 2 e o migration-plan.md da etapa 3 — é onde os 90 minutos realmente são empregados. Não planeje um intervalo dentro deste módulo. Se a turma precisar de um, faça-o na transição para o módulo 03, e não no meio das planilhas.

Roteiro

• Comece esclarecendo o que este módulo não é: ele não representa uma demora antes da migração “de verdade” do módulo 03. O motivo mais comum para uma migração do ClickHouse apresentar desempenho ruim é um problema de arquitetura, não de ajuste: as equipes movem os dados primeiro e só depois fazem o projeto.
• Diga isso diretamente, pois é o argumento mais forte para investir os 90 minutos: este é o módulo que os parceiros mais se sentem tentados a ignorar, já que o setup.sh do módulo 03 apenas avisa sobre um migration-plan.md ausente ou incompleto; ele nunca bloqueia.
• Explique o que acontece se um parceiro o ignorar mesmo assim: a execução mecânica do módulo 03 ainda terá sucesso — fact_trips ainda será criada como ReplacingMergeTree e os dados ainda serão transferidos —, mas ele não saberá por que esse mecanismo foi escolhido em vez de um MergeTree simples, não saberá como a chave ORDER BY foi derivada da carga de consultas, não reconhecerá delete_insert e FINAL nas configurações do dbt e não conseguirá explicar nem reproduzir para um cliente os ganhos do benchmark do módulo 05.
• Mostre a página de referência do exemplo completo somente depois que os parceiros tiverem tentado elaborar o próprio plano. Ela é uma verificação de coerência, não um modelo a ser copiado antes de refletir.

Falhas comuns

• ACCOUNT_USAGE não está disponível quando o script de criação de perfil da etapa 1 é executado. É preciso aguardar de 1 a 3 horas para a propagação após a criação da conta do Snowflake ou usar a função ACCOUNTADMIN. O script recorre automaticamente a INFORMATION_SCHEMA e informa o que não conseguiu medir. Trata-se de uma degradação controlada, não de uma falha, mas o parceiro pode não perceber que o fallback ocorreu. Mostre a ele scripts/02_query_history.sql, que pode ser executado manualmente na interface do Snowflake, se o perfil automatizado parecer superficial.
• Um parceiro trata a lista de verificação de conclusão em migration-plan.md como opcional. Ela não é: o setup.sh do módulo 03 a lê, e uma caixa desmarcada indica que este módulo foi ignorado na prática, mesmo que o arquivo exista.
• PENDENTE: ao contrário dos módulos 01 e 03, o README deste módulo não contém uma seção de solução de problemas. Complete estas informações após o ensaio, quando a parte das planilhas tiver sido realizada com uma turma real.

Etapas de redefinição

• profile_report.md (saída da etapa 1) é ignorado pelo Git e é gerado novamente a partir da conta Snowflake ativa do próprio parceiro em cada execução. Se parecer desatualizado ou incorreto, basta executar ./scripts/01_profile_snowflake.sh outra vez. Não há nada a desmontar.
• As cinco planilhas são preenchidas no site, com correção imediata e respostas salvas no navegador do participante (localStorage), e não no repositório. migration-plan.md continua sendo editado no próprio repositório. Este módulo não provisiona nada em nenhuma das nuvens, portanto não há teardown.sh nem opções de configuração a usar.
• Se uma planilha de um participante ficar em um estado inválido, oriente-o a usar o controle “Clear answers” da própria planilha, em vez de fazer checkout no Git. As respostas nunca foram gravadas no Git, portanto o checkout não ajudaria.