Upgrade de versão major com pg_upgrade --link (runbook de ponta a ponta)

Comando

# As the postgres user, in a writable directory; example 16 -> 17
export OLD_BIN=/usr/pgsql-16/bin NEW_BIN=/usr/pgsql-17/bin
export OLD_DATA=/var/lib/pgsql/16/data NEW_DATA=/var/lib/pgsql/17/data
# 0) initdb the new cluster with the same encoding/locale and checksum setting as the old one (-k if the old cluster has checksums)
# 1) Compatibility check (can run while the old cluster is up, changes no data):
$NEW_BIN/pg_upgrade --old-bindir=$OLD_BIN --new-bindir=$NEW_BIN --old-datadir=$OLD_DATA --new-datadir=$NEW_DATA --check
# 2) Stop the old cluster and upgrade with hard links:
$OLD_BIN/pg_ctl -D $OLD_DATA stop -m fast
$NEW_BIN/pg_upgrade --old-bindir=$OLD_BIN --new-bindir=$NEW_BIN --old-datadir=$OLD_DATA --new-datadir=$NEW_DATA --link --jobs=4
# 3) Carry postgresql.conf/pg_hba.conf customizations over to the new cluster, start it:
$NEW_BIN/pg_ctl -D $NEW_DATA -l /tmp/pg17_start.log start
# 4) Gather statistics, run generated scripts if any:
$NEW_BIN/vacuumdb --all --analyze-in-stages
# psql -X -f update_extensions.sql   (if pg_upgrade generated it)
# 5) After validation and a fresh backup, delete the old cluster:
./delete_old_cluster.sh

O que faz

Primeiro valida a compatibilidade com --check e depois faz o upgrade major em minutos, independentemente do tamanho dos dados, criando hard links dos arquivos de dados do cluster antigo para a nova versão em vez de copiá-los; em seguida coleta estatísticas em etapas e remove o cluster antigo.

Quando usar

Para migrar no próprio local um cluster grande para uma nova versão major com uma indisponibilidade aceitavelmente curta (minutos).

Atenção

Com --link, depois que o novo cluster é iniciado o cluster antigo não pode mais ser usado com segurança; a única forma de voltar é um backup feito antes do upgrade. Os diretórios de dados antigo e novo devem estar no mesmo file system. Os planos podem ser ruins no novo cluster até o analyze terminar. Se você usa pgBackRest, execute stanza-upgrade e faça um novo backup full imediatamente; backups da versão antiga não podem ser restaurados no novo cluster.