Melhores Práticas de Migrações

Regras para alteração de esquema versionada que sobrevive a deploy contínuo, tabelas grandes e rollbacks às 3 da manhã.

Como Usar Esta Lista

• Controle cada PR de migração com as seções A, B e C.
• Exija revisão de DBA para itens D em tabelas com mais de 10 milhões de linhas ou caminhos críticos de SLA.
• Revise E após cada incidente relacionado a migrações.

A - Processo e Git

• Histórico de migração ordenado único no git. Sem DDL manual em produção fora do pipeline.
• Revise migrações como código de aplicação. Mínimo de dois pares de olhos.
• Nunca edite arquivos de migração aplicados. Corrija para frente apenas com nova versão.
• CI aplica a cadeia completa a um banco de dados vazio em cada PR. Captura bugs de ordenação e permissão.
• Combine a versão principal do PostgreSQL na CI com o alvo de produção. O comportamento de extensões e DDL difere.

B - Papéis e Segurança

• Migrações executadas como app_migrator, objetos pertencentes a app_owner. O papel de tempo de execução não tem DDL.
• Defina lock_timeout no SQL da migração. Falhe rapidamente em vez de bloquear o tráfego da aplicação.
• Defina statement_timeout sensato por tipo de instrução. Alto para CONCURRENTLY, baixo para DDL de teste.
• Conceda privilégios na migração ou privilégios padrão. Sucesso do deploy sem erros de permissão em tempo de execução.
• Documente migrações não transacionais. CREATE INDEX CONCURRENTLY em arquivo separado com transação do runner desativada.

C - Design de Zero Downtime

• Expanda antes de contrair; nullable antes de NOT NULL. Mudanças que quebram em múltiplos releases.
• Use CREATE INDEX CONCURRENTLY em tabelas grandes. Verifique indisvalid após a execução.
• ADD CONSTRAINT NOT VALID e depois VALIDATE separadamente. Evite longas varreduras ACCESS EXCLUSIVE.
• Preencha em lotes com monitoramento de lag de replicação. Nenhuma transação UPDATE única de um bilhão de linhas.
• Analise tabelas após grandes alterações de dados. Estatísticas do planejador ficam obsoletas após o preenchimento.

D - Rollback e Recuperação

• ADR: esquema apenas para frente em produção. A aplicação faz rollback; o esquema avança com migração de correção.
• Teste a compatibilidade do rollback da aplicação com o esquema da fase de expansão. O binário antigo deve rodar em novas colunas nullable.
• Backup ou checkpoint PITR antes de migrações de contração. DROP COLUMN é irreversível sem restauração.
• Scripts de rollback do Liquibase/Flywave executam apenas em clones. Não são executados automaticamente em produção.
• Feature flags coordenam fases de esquema. Chave de desligamento sem migração de contração.

E - Observabilidade

• Registre a duração da migração e esperas de lock no pipeline de deploy. Tendência de longos executores antes que bloqueiem a produção.
• Alerta sobre índices inválidos após o deploy. CONCURRENTLY falho deixa armadilhas.
• Consultas de smoke test pós-deploy em CI/CD. psql -f assert_schema.sql com ON_ERROR_STOP.
• Rastreie a propriedade da migração em CODEOWNERS. A equipe de dados revisa db/migration/**.
• Inclua estimativas de contagem de linhas na descrição do PR para DDL grande. Define as expectativas do revisor.

FAQs

Relacionados

• Noções Básicas de Migrações - fundamentos
• DDL de Zero Downtime - padrões concorrentes
• Regras de Segurança de Migração - lista de regras

Versões de Stack: Esta página foi escrita para PostgreSQL 18.4 (estável 18, manutenção 17), pgvector 0.8+, PgBouncer 1.x, Patroni 3.x e PostGIS 3.5+.