Mapeie cada leitor e gravador
Trabalhe em um esquema isolado com dados sanitizados representativos. Você precisa das versões atual e próxima da aplicação, conhecimento do seu framework de migração, uma estratégia de backup revisada e visibilidade sobre transações longas. Inclua workers, jobs agendados, relatórios e instâncias mais antigas da aplicação. Uma API pode atualizar rapidamente enquanto um worker de longa duração ainda grava na coluna antiga.
Nosso serviço de relatórios ilustrativo armazena um rótulo de exportação em label e quer display_name. Este é um exemplo de design, não SQL universal executável. Confirme sua versão exata do PostgreSQL e framework antes de escolher a sintaxe de migração ou as configurações de lock.
Expanda sem aposentar a representação antiga
Introduza primeiro o novo campo anulável. Implante uma versão de compatibilidade que grave ambos os valores em uma única transação e leia com o fallback necessário enquanto os dados estiverem incompletos. Defina o que acontece quando um cliente edita um registro durante o backfill. Uma nova tentativa não deve criar uma segunda exportação lógica.
PostgreSQL ALTER TABLE as operações adquirem locks, com o nível dependendo do subcomando. Uma pequena alteração pode esperar atrás de uma transação longa e então obstruir outro trabalho. Revise a operação específica e observe as esperas durante o ensaio; aditivo não significa livre de locks.
Referência técnica: PostgreSQL ALTER TABLE · Bloqueio explícito no PostgreSQL.
Torne visível a fronteira de compatibilidade
| Esquema e gravadores | Comportamento do leitor | Decisão de recuperação |
|---|---|---|
| Apenas o rótulo existe | Código antigo suportado | Adicione o novo campo primeiro |
| Ambos os campos; gravadores apenas antigos permanecem | Leia o rótulo como autoritativo | Ainda não troque os leitores |
| Todos os gravadores gravam em ambos; backfill verificado | O novo campo pode se tornar autoritativo | Rollback apenas para código compatível de gravação dupla |
| Campo antigo removido | Nenhum código pode referenciar o rótulo | O artefato antigo é incompatível |
Um fallback para valores ausentes não consegue detectar um novo valor não nulo, mas desatualizado. Antes de trocar os leitores, aposente os gravadores apenas antigos e verifique a consistência. Reverter para código apenas antigo após a troca de leitores pode recriar divergência. Mantenha a versão de compatibilidade como o artefato de recuperação revisado.
Faça backfill em trabalho limitado e reiniciável
Encontre linhas que precisam ser copiadas sem sobrescrever uma edição mais recente do cliente. Use uma ordenação estável, uma condição de atualização segura para concorrência e lotes escolhidos para a carga de trabalho. Persista o progresso para que uma falha possa ser retomada em um limite conhecido. Monitore o volume de gravação, esperas de lock, latência de requisições e replicação, quando presente.
Nenhum tamanho de lote é seguro para toda aplicação. No ensaio, compare um lote pequeno com o tráfego normal e depois escolha uma regra de pausa ou parada. Se um lote falhar, inspecione o que foi confirmado antes de tentar novamente. Um loop de repetição ilimitado pode transformar uma inconsistência recuperável em pressão sustentada no banco de dados.
Verifique a semântica, não apenas as linhas preenchidas
Verifique valores ausentes, rótulos representativos, novos registros e atualizações de exportações existentes. Contar linhas não nulas pode parecer correto enquanto valores foram copiados da origem errada. Teste o artefato de compatibilidade com dados parcialmente preenchidos e exercite um worker iniciado antes da implantação.
Registre a versão do esquema, a revisão da migração, os critérios de conclusão e as combinações incompatíveis. Inspecione o uso do fallback e a consistência antes de remover qualquer um dos dois. Se as verificações falharem, pare o backfill ou a promoção, preserve evidências e escolha um artefato compatível ou um reparo progressivo revisado. Não afirme que um rollback da aplicação reconstrói dados confirmados.
Aposente o campo antigo em outra versão revisada
Remova leituras e gravações antigas após o backfill e o período de observação atenderem aos seus critérios. Verifique jobs pouco frequentes, bem como rotas interativas. Remover o campo antigo pertence a uma alteração posterior com sua própria decisão de recuperação, para que um problema de versão não o force a combinar reparo de código com reconstrução de dados.
Se dados ruins aparecerem após a aposentadoria, pare danos adicionais e use o plano de recuperação ou um reparo aprovado. Não aplique uma migração reversa destrutiva só porque a ferramenta expõe um botão de rollback. Anexe a matriz ao registro de versão e ensaie recuperação de dados antes de alterar a produção. O resultado útil é uma fronteira de compatibilidade explícita, não uma garantia de zero downtime.
Referências oficiais
A documentação foi revisada para este artigo. Os exemplos são exercícios de planejamento, não comandos testados em um servidor PrivacyNodes. Verifique a documentação da sua versão instalada.