Todos os artigos

Migration sem derrubar a aplicação: o padrão de 4 fases para alterar schema em produção

"Vamos só renomear uma coluna" é a frase que precede a maioria das janelas de manutenção que ninguém precisava ter agendado. O problema não é o schema — é misturar mudança de schema com deploy da aplicação no mesmo passo.

Quinta-feira, 23h. O time está esperando o deploy. O plano é simples: rodar a migration que renomeia user_email para email, fazer o deploy da aplicação que usa o novo nome, e ir dormir. A migration roda em 4 segundos. A aplicação leva 90 segundos para todas as réplicas trocarem. Nesses 86 segundos no meio, metade das requisições explode com column user_email does not exist.

O problema não é o schema. É ter tratado a mudança de schema e o deploy da aplicação como uma operação atômica — quando, na prática, são duas operações que rodam em ordens diferentes em cada réplica. Migration sem downtime existe porque alguém se cansou disso e separou os passos.

Por que o rolling deploy quebra com migration síncrona

Em produção, sua aplicação não atualiza instantaneamente. Ela tem N réplicas que vão sendo trocadas em janelas de poucos segundos cada. Durante essa janela, o sistema vive num estado misto: parte das réplicas roda código novo, parte roda código antigo, e todas apontam para o mesmo banco.

Se o schema mudou de forma incompatível com o código antigo, as réplicas antigas falham. Se mudou de forma incompatível com o código novo, as réplicas novas falham. A única migration realmente segura é aquela que funciona para os dois ao mesmo tempo.

Migration sem downtime não é uma migration mais rápida. É uma sequência de migrations pequenas, em que nenhum estado intermediário quebra a aplicação.

O padrão expand-contract em 4 fases

A ideia é dividir o que parecia ser uma única operação em quatro deploys independentes, cada um deixando o sistema num estado válido para o anterior e o próximo. O nome formal é expand-contract, ou parallel change. Funciona para renomear, dividir, juntar ou trocar tipo de coluna — não só os casos triviais.

Fase Schema Aplicação Risco
1. Expand Adiciona o novo, mantém o antigo Continua usando o antigo Mínimo
2. Migrate Backfill do novo Escreve nos dois, lê do antigo Baixo
3. Contract Sem mudança Lê e escreve só do novo Médio (rollback trivial)
4. Cleanup Remove o antigo Já não usa o antigo Mínimo

Fase 1 — Expand

A primeira migration só adiciona. Cria a coluna email ao lado de user_email, nullable, sem default que cause rewrite da tabela inteira. A aplicação continua usando exclusivamente user_email. Nada quebra porque adicionar coluna nullable é, em bancos relacionais modernos, uma operação não-bloqueante de metadado.

Fase 2 — Migrate (escrita dupla + backfill)

Aqui é onde a maior parte dos times tropeça. Deploy da aplicação para escrever nas duas colunas simultaneamente. Em paralelo, um job de backfill copia os valores existentes de user_email para email, em lotes pequenos para não travar o banco. A leitura ainda vem do antigo — se algo der errado, basta parar a escrita dupla.

Fase 3 — Contract

Com o backfill terminado e a escrita dupla rodando há tempo suficiente para garantir que toda nova linha tem os dois campos preenchidos, o próximo deploy aponta a aplicação exclusivamente para a coluna nova. Lê de email, escreve em email. A coluna antiga ainda existe — intocada, apenas dormindo. Se aparecer algum problema com o código novo, o rollback é um deploy: volta para a versão da fase 2 e nada se perde.

Fase 4 — Cleanup

Depois de alguns dias com a fase 3 estável em produção, finalmente cai o ALTER TABLE DROP COLUMN user_email. É um deploy sem mudança de aplicação. A coluna antiga sai do banco, o ciclo fecha, e a quinta-feira às 23h volta a ser horário de jantar.

Regra prática

Cada fase é um deploy separado, com observação no meio. Acelerar duas fases num único deploy economiza minutos hoje e introduz exatamente o tipo de bug que o padrão existe para evitar. Não trapaceie nas fases.

Quando o padrão não vale a pena

Expand-contract tem overhead real: quatro deploys, escrita dupla, código que precisa lidar com duas representações durante semanas. Não vale a pena em todo caso:

  • Tabela pequena e janela de manutenção aceitável. Se o sistema admite 30 segundos de indisponibilidade semanal e a tabela tem 10 mil linhas, o overhead do padrão custa mais do que a janela.
  • Mudança aditiva pura. Adicionar coluna nullable nova, que nenhum código antigo lê, é seguro em um deploy só. Não precisa do padrão completo.
  • Sistema sem rolling deploy. Se sua aplicação roda em uma instância única que reinicia inteira, o problema das réplicas em estados diferentes não existe — e o padrão resolve um problema que você não tem.

Conclusão

A migration sem downtime não é, como muitas vezes se vende, um superpoder de quem tem time grande. É uma disciplina de separar o que é mudança de dado do que é mudança de comportamento — e tratar cada uma com o cuidado que ela merece. O custo é fazer quatro deploys onde antes fazia um. O ganho é nunca mais precisar marcar manutenção para "uma renomeação simples".

Se você ainda agenda janela de manutenção para alterar schema, comece por aqui: na próxima migration que parecer pequena, escreva os quatro deploys antes de rodar o primeiro. Você vai descobrir, no caminho, quanta complexidade estava sendo escondida pela palavra "rápido".

Blog & Insights

Perspectiva técnica de quem está na prática.

Conteúdo real para CTOs, diretores de produto e decisores que querem entender o que funciona em desenvolvimento de software.

UX/UI 10 JUN 2025

Discovery contínuo para times pequenos: o framework de 4 horas por semana

Como manter pesquisa qualitativa rodando sem afundar o time de produto em entrevistas que ninguém vai assistir depois.

Ler
Produto 03 JUN 2025

MVP não é produto ruim: como validar rápido sem dívida técnica

Estratégias para chegar ao mercado em semanas sem comprometer arquitetura.

Ler
Gestão 26 MAI 2025

Como selecionar uma empresa de desenvolvimento sem se arrepender

O checklist que todo CTO deveria usar antes de assinar qualquer contrato.

Ler
VAMOS DAR O PRÓXIMO PASSO

Seu desafio merece uma boa conversa.

Conte como sua operação funciona e o que você gostaria de transformar.

Vamos conversar