Por que rodar um ALTER TABLE destrutivo no pipeline de deploy derruba seu cluster Kubernetes e como evoluir esquemas de banco sem parar a operação.
Todo time que adota Kubernetes aprende rapidamente a configurar Rolling Updates: enquanto os novos pods da versão v2 sobem e passam pelos readiness probes, os pods antigos da versão v1 continuam atendendo os usuários até serem desligados graciosamente. Na teoria, o deploy acontece com zero indisponibilidade (zero-downtime).
Na prática, essa promessa costuma desmoronar no primeiro deploy que altera o esquema do banco de dados relacional. O motivo é simples: durante a janela de transição do rolling update, a versão antiga e a versão nova do código compartilham exatamente o mesmo banco de dados ao mesmo tempo.
Se o seu pipeline executa uma migration destrutiva — como renomear uma coluna, alterar um tipo de dado ou remover um campo legado — antes ou durante a subida dos novos pods, metade das requisições em produção começará a falhar instantaneamente. Para resolver esse problema na raiz, a arquitetura de dados moderna utiliza o padrão Expand and Contract (também conhecido como Parallel Change).
O Problema: A Janela de Incompatibilidade entre v1 e v2
Quando acoplamos mudanças de código e mudanças destrutivas de banco no mesmo deploy, caímos em um beco sem saída operacional:
- Se a migration roda antes do código novo subir: Os pods antigos (v1) ainda estão recebendo tráfego e tentam consultar ou gravar na coluna que acabou de ser renomeada ou removida. Resultado: erro 500 imediato.
- Se o código novo sobe antes da migration rodar: Os pods novos (v2) tentam acessar a coluna nova que ainda não existe no banco. Resultado: erro 500 imediato.
O Cenário do Desastre:
Durante a preparação para uma campanha de grande volume, um desenvolvedor decide padronizar a tabela pedidos renomeando a coluna nome_cliente para nome_completo via ALTER TABLE pedidos RENAME COLUMN nome_cliente TO nome_completo. O pipeline executa a migration antes de substituir os containers no Kubernetes. Nos 90 segundos em que os pods v1 ainda estão ativos, milhares de pedidos de checkout falham com Column 'nome_cliente' does not exist, derrubando a conversão e gerando incidentes críticos em cadeia.
A Solução: As Quatro Fases do Expand and Contract
Em vez de tentar alterar o banco de forma atômica e destrutiva, o padrão Expand and Contract divide a evolução do schema em etapas pequenas, seguras e 100% retrocompatíveis:
- Fase 1 — Expand (Expandir): Adicione a nova coluna (
nome_completo) como opcional (NULLABLE), mantendo a coluna antiga intacta. Suba uma versão do código que escreve nas duas colunas simultaneamente (na mesma transação local) e lê da nova com fallback para a antiga caso esteja nula. - Fase 2 — Backfill (Preencher o Histórico): Execute um script ou job em lotes pequenos (batches) para copiar os valores antigos de
nome_clienteparanome_completonos registros criados antes do deploy, sem gerar locks prolongados na tabela. - Fase 3 — Switch (Virar a Chave): Quando 100% dos registros estiverem preenchidos e todos os pods antigos desligados, a aplicação passa a ler e escrever apenas na coluna nova. Se necessário, aplica-se a constraint
NOT NULLde forma segura. - Fase 4 — Contract (Contrair): Somente em um deploy posterior — após confirmar que nenhuma instância v1 existe mais no cluster — você remove a coluna antiga
nome_cliente.
Implementação Prática em SQL e Python: Transição e Backfill Seguro
Veja como estruturar a camada de transição e o script de backfill controlado em Python (usando psycopg / PostgreSQL) sem travar a tabela de produção:
# migration_expand_contract.py
import time
import psycopg
# 1. Na Fase EXPAND (Código da aplicação durante a convivência v1/v2)
def salvar_pedido_compativel(conn, pedido_id: str, nome: str):
"""Escreve nas duas colunas na mesma transação para manter v1 e v2 felizes."""
with conn.cursor() as cur:
cur.execute(
"""
INSERT INTO pedidos (id, nome_cliente, nome_completo)
VALUES (%s, %s, %s)
""",
(pedido_id, nome, nome),
)
conn.commit()
def ler_nome_cliente_compativel(row: dict) -> str:
"""Lê prioritariamente da nova coluna, com fallback seguro para a legada."""
return row.get("nome_completo") or row.get("nome_cliente")
# 2. Na Fase BACKFILL (Job executado em lotes pequenos para evitar locks de tabela)
def executar_backfill_em_lotes(dsn: str, tamanho_lote: int = 1000):
with psycopg.connect(dsn) as conn:
while True:
with conn.cursor() as cur:
# Atualiza apenas um lote restrito usando CTID/Subquery para não travar a tabela
cur.execute(
"""
UPDATE pedidos
SET nome_completo = nome_cliente
WHERE id IN (
SELECT id FROM pedidos
WHERE nome_completo IS NULL
LIMIT %s
FOR UPDATE SKIP LOCKED
)
""",
(tamanho_lote,),
)
linhas_afetadas = cur.rowcount
conn.commit()
if linhas_afetadas == 0:
print("[BACKFILL] Todos os registros históricos foram migrados com sucesso.")
break
print(f"[BACKFILL] Lote de {linhas_afetadas} registros atualizado.")
# Pausa breve para dar fôlego ao I/O do banco e evitar atraso na réplica
time.sleep(0.2)
Repare no detalhe do FOR UPDATE SKIP LOCKED e do time.sleep(0.2): em tabelas com dezenas de milhões de linhas, um UPDATE global sem limite trava transações concorrentes de checkout e dispara alertas de Replication Lag. O processamento em lotes com pausa mantém o banco respirando normalmente em horário comercial.
As Três Regras de Ouro de Migrations em Produção
- Proíba RENAME e DROP Diretos: Se você precisa renomear uma coluna ou mudar seu tipo de dado, nunca faça em um único passo. Trate sempre como uma operação de adição, coexistência e remoção posterior.
- Cuidado com Locks ao Criar Índices e Constraints: Em bancos como o PostgreSQL, criar um índice comum bloqueia escritas na tabela inteira. Utilize sempre
CREATE INDEX CONCURRENTLYe adicione novas colunas inicialmente comoNULLsem valores padrão computados pesados. - Separe o Deploy da Migration de Limpeza: A fase de Contract (remover a coluna antiga) deve ocorrer sempre em um Pull Request e deploy separados, dias ou horas depois de validar que a nova versão está 100% estável em produção e nenhum rollback será necessário.
Conclusão
Fazer zero-downtime deployment de verdade exige aceitar que, enquanto o código das aplicações é efêmero e substituível em segundos no Kubernetes, o estado do banco de dados é compartilhado e persistente.
Ao adotar o padrão Expand and Contract, você elimina o pânico das alterações de schema, garante que versões antigas e novas coexistam pacificamente durante o rolling update e transforma evoluções de banco de dados em rotinas previsíveis e totalmente reversíveis.