Zero-Downtime Database Migrations: O Padrão Expand and Contract na Prática

Servidores de banco de dados e infraestrutura de alta disponibilidade

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:

  1. 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.
  2. Fase 2 — Backfill (Preencher o Histórico): Execute um script ou job em lotes pequenos (batches) para copiar os valores antigos de nome_cliente para nome_completo nos registros criados antes do deploy, sem gerar locks prolongados na tabela.
  3. 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 NULL de forma segura.
  4. 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

  1. 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.
  2. 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 CONCURRENTLY e adicione novas colunas inicialmente como NULL sem valores padrão computados pesados.
  3. 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.