PostgreSQL major upgrade (pg_upgrade / logical replication)

Upgrade de versão principal (ex.: 16 → 17): escolha do método (pg_upgrade --link / --copy / --clone ou migração quase sem downtime com logical replication), pg_upgrade --check, compatibilidade das extensões, migração da configuração, nova coleta de estatísticas, recriação dos standbys com rsync ou pg_basebackup, remoção do cluster antigo e runbook de rollback. Servidor único, streaming replication (primary + standbys) e cluster Patroni (procedimento oficial de major upgrade do Patroni: o Patroni é parado, pg_upgrade no leader, o registro no DCS é removido, as replicas são clonadas novamente pelo Patroni). Família RHEL e Debian/Ubuntu (incluindo pg_upgradecluster).

Para atualizar dentro da mesma versão principal (ex.: 17.4 → 17.6), use pg-minor-update em vez deste guia. Para replicação contínua no nível de tabela ou migração parcial, use pg-logical-repl; para mover um banco de dados pequeno para outro servidor com dump, use pg-dump-restore.

Topologia: In-place no mesmo servidor (pg_upgrade; servidor único, primary + standbys ou cluster Patroni) ou para um novo servidor (logical)

Cenários

• Major upgrade — Upgrade de versão principal (ex.: 16 → 17): pré-verificações, backup, pg_upgrade ou logical replication, verificação e limpeza.
• Rollback (upgrade falhou / foi abandonado) — O upgrade parou no meio ou a nova versão apresentou problemas: voltar para a versão antiga. Com --link, se o novo cluster já foi iniciado, só é possível voltar pelo backup.

Antes de começar

• O cluster de origem é PostgreSQL …, instalado a partir do repositório PGDG (pg-install). A versão de destino … é maior que a de origem.
• A aplicação e os drivers foram testados com PostgreSQL …; o mesmo upgrade foi ensaiado antes em um ambiente de testes. As seções "Migration to Version" das release notes de cada versão principal até a … foram lidas (parâmetros removidos, mudanças de comportamento).
• Existe uma versão para … de todas as extensões instaladas (PostGIS, pg_repack, pgaudit, TimescaleDB…). Se uma extensão não existir para …, o upgrade não pode ser feito.
• …Há espaço livre igual ao tamanho atual dos dados para o novo diretório de dados.…Os diretórios de dados antigo e novo estão no mesmo sistema de arquivos (requisito dos hard links); há alguns GB livres para WAL e para o novo catálogo.…O sistema de arquivos suporta reflink (XFS reflink=1 ou Btrfs) e os dois diretórios estão no mesmo sistema de arquivos.…
• Os logical replication slots / subscriptions existentes foram listados: …com origem PostgreSQL 17+, o pg_upgrade migra os logical slots, mas todas as alterações precisam ter sido consumidas…com origem PostgreSQL …, o pg_upgrade não migra os logical slots; eles precisam ser recriados após o upgrade….
• Há SSH sem senha com o usuário postgres do primary para cada standby, e o rsync está instalado nos standbys. O layout do diretório de dados é …/<version>/data (o rsync usa o diretório pai comum).
• Os standbys estão em streaming; o pg_hba.conf do primary permite a conexão de replicação e a senha de … está em ~postgres/.pgpass nos standbys.
• O cluster Patroni está saudável: … é o leader atual, todas as replicas estão streaming sem lag, sem Pending restart. Nome do cluster …, configuração …, senhas da REST API em /etc/patroni/patroni.env (layout do pg-patroni). Foi feito um backup por snapshot do DCS (etcd). Durante o upgrade o cluster ficará totalmente parado: conexões via HAProxy/VIP serão recusadas.
• A versão do Patroni suporta PostgreSQL … (suporte à nova versão principal nas release notes do Patroni). Um Patroni antigo pode não reconhecer os parâmetros e o arquivo de controle da nova versão; se necessário, atualize primeiro o Patroni de forma rolling.
• No servidor de destino o PostgreSQL … foi instalado com pg-install, está vazio e em execução; as versões … das extensões da origem estão instaladas. O destino consegue acessar a porta … da origem.
• As tabelas a migrar têm primary key ou replica identity (caso contrário, UPDATE/DELETE falham na origem). Adicione uma PK às tabelas listadas ou aplique ALTER TABLE … REPLICA IDENTITY FULL.
• Existe um backup atual com restore testado… (pgBackRest)…; se possível, também será feito um snapshot do servidor/disco.… No método --link, este é o único caminho de volta depois que o novo cluster é iniciado.…

Fases do guia

• Pré-verificação — Verificar o estado do cluster Patroni · Registrar as características do cluster · Listar os RPM/deb das extensões · Verificar prepared transactions e transações longas
• Preparação do novo cluster — Criar o novo diretório de dados · Criar o novo cluster com as mesmas características (initdb) · Migrar a configuração para o novo cluster · Verificar se há configurações inválidas na nova versão · Verificar os parâmetros do Patroni para a nova versão
• Backup e ponto de retorno — Fazer backup (pgBackRest full) · Fazer backup (pg_dumpall + snapshot)
• Verificação de compatibilidade (pg_upgrade --check) — pg_upgrade --check
• Downtime: parar o cluster antigo — Parar as aplicações · Último backup no momento do downtime (pgBackRest incr) · Último backup lógico no momento do downtime · Parar o primary antigo · Parar o Patroni nas replicas · Parar o Patroni no leader …
• Upgrade — Executar o pg_upgrade · Fazer o upgrade com pg_upgradecluster · Migrar os arquivos de conf.d para o novo cluster · Apontar a configuração do pgBackRest para o novo cluster · Apontar bin_dir e data_dir do patroni.yml para a nova versão · Atualizar a stanza do pgBackRest para a nova versão …
• Inicialização do novo cluster — Iniciar o novo cluster · Iniciar o Patroni no leader · Iniciar os standbys imediatamente
• Tarefas após o upgrade — Atualizar as extensões · Coletar estatísticas · Verificação do pgBackRest e novo backup full
• Verificação — Versão, configurações e bancos de dados · Verificar o cluster Patroni · Verificar os logs · Testes da aplicação
• Remoção do cluster antigo — Apagar o diretório de dados antigo · Apagar o diretório de dados antigo …nas replicas…nos standbys… · Remover o software da versão antiga
• Preparação do servidor de origem — wal_level = logical · Reiniciar a origem · Criar o usuário de replicação · Adicionar o destino ao pg_hba.conf · Recarregar o pg_hba · Criar a publication
• Schema e subscription no destino — Gravar as senhas da origem no .pgpass · Copiar as roles (globals) · Copiar o schema · Criar a subscription · Aguardar o fim da cópia inicial · Verificar o lag
• Virada final (cutover) — Interromper as gravações na origem · Confirmar que as últimas alterações foram transferidas · Transferir os valores das sequences · Remover a subscription · Coletar estatísticas · Redirecionar as aplicações para o destino …
• Rollback — Parar o novo cluster · Parar o Patroni nas replicas · Parar o Patroni no leader · Restaurar o pg_control (--link, novo cluster não iniciado) · …Voltar pelo backup (--link, novo cluster iniciado)…Voltar pelo backup lógico (--link, novo cluster iniciado)… · Concluir o recovery sem o Patroni …