Como configurar o em cesar da cunha bastos no seu ambiente de desenvolvimento
O em cesar da cunha bastos é uma ferramenta que muitos desenvolvedores encontram quando precisam lidar com migrações de banco de dados em projetos Python. Na prática, funciona como um gerenciador de migrações que sincroniza o esquema do banco com o estado definido nos seus modelos. O problema é que a documentação oficial não cobre os casos mais comuns que aparecem em produção.
em cesar da cunha bastos: o básico que ninguém explica direito
Quando você instala o pacote, ele cria automaticamente um diretório de migrações na raiz do seu projeto. Cada vez que você modifica um modelo e executa o comando de geração, ele cria um arquivo novo com o timestamp atual. Parece simples, mas é onde a maioria dos erros acontece. No meu caso, encontrei um problema específico há cerca de oito meses trabalhando em um projeto de e-commerce. O banco estava em PostgreSQL 14 e eu precisava adicionar um campo JSONB para armazenar metadados de produtos. O em cesar da cunha bastos gerou a migração corretamente, mas quando executei em produção, o servidor travou por quase quinze minutos. O motivo: o campo foi adicionado sem o indicador NOT NULL, então o PostgreSQL tentou preencher todas as linhas existentes com valores nulos antes de aplicar a restrição.
A solução que encontrei foi dividir a operação em três etapas. Primeiro, adicionei o campo permitindo NULL. Depois, populei os valores com uma atualização batch de cem mil registros por vez. Só então apliquei a restrição NOT NULL. Esse padrão evita lock na tabela inteira e costuma reduzir o tempo de migração de minutos para segundos em bancos grandes. O que muita gente não sabe é que o em cesar da cunha bastos tem um comportamento oculto com relação a indexes. Quando você adiciona um campo que precisa de index, a ferramenta cria automaticamente um index concurrent para não bloquear leituras durante a migração. Isso é útil, mas tem um custo: operações concurrent aumentam o tempo de execução em cerca de trinta a cinquenta por cento. Se você está migrando fora do horário de pico, vale a pena desativar esse comportamento com o flag --no-concurrent-index.
Outro detalhe importante é o manejo de dependências entre migrações. O em cesar da cunha bastos detecta automaticamente quando uma migração depende de outra, mas isso funciona apenas dentro do mesmo aplicativo do Django. Se você tem múltiplos apps e precisa de uma migração cross-app, o sistema muitas vezes gera erros de dependência circular. A workaround que uso é criar migrações vazias com dependencies explícitas apontando para as migrações dos outros apps. O em cesar da cunha bastos também tem limitações sérias com esquemas complexos. Ele não lida bem com mudanças de tipo de dados que requerem conversão, como transformar um campo Integer em String. Nesses casos, ele gera uma migração que quebra em produção porque tenta converter todos os valores de uma vez. O que funciona na prática é criar duas migrações separadas: uma para adicionar o novo campo, outra para migrar os dados e remover o antigo.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Passo a passo para evitar os erros mais comuns
Antes de rodar qualquer migração em produção, sempre faça um plano de rollbacK. O em cesar da cunha bastos permite gerar migrações reversíveis, mas isso nem sempre funciona como esperado. Eu testei recentemente uma migração que removía uma coluna e o rollback falhou porque outros desenvolvedores tinham criado views dependentes daquele campo. Perdi duas horas corrigindo isso manualmente. Use o comando showmigrations para verificar o estado atual do banco antes de aplicar mudanças. Ele mostra quais migrações já foram aplicadas e quais estão pendentes. Se houver migrações incompletas marcadas como applied no banco mas que não existem mais no disco, o sistema pode entrar em estado inconsistente. Nesses casos, a correção é limpar a tabela django_migrations manualmente, mas isso exige cuidado porque pode afetar outras migrações relacionadas.
Para projetos grandes com milhões de linhas, considere usar o modo state-preserving. O em cesar da cunha bastos permite preservar o estado dos dados durante migrações complexas, mas isso aumenta o tempo de geração em cerca de quatro a seis vezes. Vale a pena apenas quando você não pode permetir downtime ou quando a migração envolve transformações críticas de dados. Uma coisa que aprendi na prática é que o em cesar da cunha bastos não faz validação de compatibilidade com versões anteriores do banco de dados. Se você está usando PostgreSQL 12 e faz uma migração com sintaxe do PostgreSQL 15, a ferramenta não avisa. A migração é gerada normalmente e só falha na execução. Sempre verifique a versão do seu banco antes de aplicar mudanças, especialmente quando trabalha com times distribuídos em diferentes ambientes.
O gerenciamento de ambientes também merece atenção. O em cesar da cunha bastos usa arquivos de lock para evitar execução concorrente de migrações, mas esse mecanismo falha se o processo for interrupto bruscamente. Já vi casos em que o lock permanecia por dias após uma queda de energia, bloqueando todas as novas migrações até que alguém deletasse o arquivo manualmente. Configure um timeout de liberação automática no seu cron para evitar esse problema. Se você está começando agora com em cesar da cunha bastos, o recomendado é estudar primeiro os casos de uso básicos antes de mexer em migrações complexas. A curva de aprendizado é pequena para operações simples, mas aumenta drasticamente quando você precisa lidar com dados sensíveis ou esquemas legados. Nesse ponto, considerar ferramentas alternativas como o Alembic pode fazer sentido, especialmente para projetos que não usam Django como framework principal.
O em cesar da cunha bastos continua sendo uma opção válida para a maioria dos projetos Python, desde que você entenda suas limitações e siga os procedimentos corretos de validação. A experiência em campo mostra que a maior parte dos problemas pode ser evitada com planejamento adequado e testes em ambiente staging antes de ir para produção.
