Montée de version majeure PostgreSQL (pg_upgrade / logical replication)

Montée de version majeure (par ex. 16 → 17) : choix de la méthode (pg_upgrade --link / --copy / --clone, ou migration quasi sans interruption par logical replication), pg_upgrade --check, compatibilité des extensions, reprise de la configuration, nouvelle collecte des statistiques, reconstruction des standbys avec rsync ou pg_basebackup, suppression de l'ancien cluster et runbook de retour arrière. Serveur unique, streaming replication (primary + standbys) et cluster Patroni (procédure officielle de montée de version majeure de Patroni : arrêt de Patroni, pg_upgrade sur le leader, suppression de l'enregistrement DCS, nouvelle copie des replicas par Patroni). Famille RHEL et Debian/Ubuntu (pg_upgradecluster compris).

Pour une mise à jour au sein de la même version majeure (par ex. 17.4 → 17.6), utilisez pg-minor-update et non ce guide. Pour une réplication continue au niveau table ou une migration partielle, utilisez pg-logical-repl ; pour déplacer une petite base vers un autre serveur par dump, pg-dump-restore.

Topologie: Sur place, sur le même serveur (pg_upgrade ; serveur unique, primary + standbys ou cluster Patroni) ou vers un nouveau serveur (logical)

Scénarios

• Montée de version majeure — Montée de version majeure (par ex. 16 → 17) : contrôles préalables, sauvegarde, pg_upgrade ou logical replication, vérification et nettoyage.
• Retour arrière (upgrade échoué / abandonné) — L'upgrade s'est arrêté en cours de route ou la nouvelle version pose problème : retour à l'ancienne version. Avec --link, si le nouveau cluster a été démarré, le retour n'est possible qu'à partir de la sauvegarde.

Avant de commencer

• Le cluster source est en PostgreSQL …, installé depuis le dépôt PGDG (pg-install). La version cible … est supérieure à la source.
• L'application et les pilotes ont été testés avec PostgreSQL … ; la même montée de version a été répétée au préalable dans un environnement de test. Les sections « Migration to Version » des release notes de chaque version majeure jusqu'à … ont été lues (paramètres supprimés, changements de comportement).
• Toutes les extensions installées existent en version … (PostGIS, pg_repack, pgaudit, TimescaleDB…). Si une extension n'existe pas pour …, la montée de version est impossible.
• …Il y a pour le nouveau répertoire de données un espace libre égal à la volumétrie actuelle.…L'ancien et le nouveau répertoire de données sont sur le même système de fichiers (condition des liens physiques) ; quelques Go libres pour le WAL et le nouveau catalogue.…Le système de fichiers prend en charge reflink (XFS reflink=1 ou Btrfs) et les deux répertoires sont sur le même système de fichiers.…
• Les logical replication slots / subscriptions éventuels ont été listés : …avec une source PostgreSQL 17+, pg_upgrade migre les slots logiques, mais toutes les modifications doivent avoir été consommées…avec une source PostgreSQL …, pg_upgrade ne migre pas les slots logiques ; ils doivent être recréés après l'upgrade….
• SSH sans mot de passe en tant qu'utilisateur postgres du primary vers chaque standby, et rsync installé sur les standbys. Les répertoires de données suivent la structure …/<version>/data (rsync utilise le répertoire parent commun).
• Les standbys sont en streaming ; le pg_hba.conf du primary autorise la connexion de réplication et le mot de passe de … se trouve dans ~postgres/.pgpass sur les standbys.
• Le cluster Patroni est sain : … est le leader actuel, tous les replicas sont streaming sans retard, aucun Pending restart. Nom du cluster …, configuration …, mots de passe de l'API REST dans /etc/patroni/patroni.env (structure pg-patroni). Un snapshot du DCS (etcd) a été sauvegardé. Pendant l'upgrade, le cluster sera entièrement arrêté : les connexions via HAProxy/VIP sont refusées.
• La version de Patroni prend en charge PostgreSQL … (support de la nouvelle version majeure dans les release notes de Patroni). Un Patroni ancien peut ne pas reconnaître les paramètres et le fichier de contrôle de la nouvelle version ; si nécessaire, mettez d'abord Patroni à jour en mode rolling.
• PostgreSQL … est installé sur le serveur cible avec pg-install, vide et démarré ; les versions … des extensions de la source sont installées. La cible peut joindre le port … de la source.
• Les tables à migrer ont une clé primaire ou une replica identity (sinon UPDATE/DELETE échouent sur la source). Ajoutez une PK aux tables listées ou appliquez ALTER TABLE … REPLICA IDENTITY FULL.
• Il existe une sauvegarde récente dont la restauration a été testée… (pgBackRest)… ; si possible, un snapshot serveur/disque sera aussi pris.… Avec la méthode --link, c'est la seule voie de retour une fois le nouveau cluster démarré.…

Phases du guide

• Contrôles préalables — Vérifier l'état du cluster Patroni · Relever les propriétés du cluster · Lister les RPM/deb des extensions · Vérifier les transactions préparées et les transactions longues
• Préparation du nouveau cluster — Créer le nouveau répertoire de données · Créer le nouveau cluster avec les mêmes propriétés (initdb) · Reprendre la configuration dans le nouveau cluster · Vérifier les paramètres invalides dans la nouvelle version · Vérifier les paramètres Patroni par rapport à la nouvelle version
• Sauvegarde et point de retour — Prendre une sauvegarde (pgBackRest full) · Prendre une sauvegarde (pg_dumpall + snapshot)
• Contrôle de compatibilité (pg_upgrade --check) — pg_upgrade --check
• Interruption : arrêter l'ancien cluster — Arrêter les applications · Dernière sauvegarde au début de l'interruption (pgBackRest incr) · Dernière sauvegarde logique au début de l'interruption · Arrêter l'ancien primary · Arrêter Patroni sur les replicas · Arrêter Patroni sur le leader …
• Upgrade — Lancer pg_upgrade · Monter de version avec pg_upgradecluster · Reprendre les fichiers conf.d dans le nouveau cluster · Basculer la configuration pgBackRest vers le nouveau cluster · Basculer bin_dir et data_dir de patroni.yml vers la nouvelle version · Mettre à niveau la stanza pgBackRest vers la nouvelle version …
• Démarrage du nouveau cluster — Démarrer le nouveau cluster · Démarrer Patroni sur le leader · Démarrer les standbys immédiatement
• Opérations après l'upgrade — Mettre à jour les extensions · Collecter les statistiques · Contrôle pgBackRest et nouvelle sauvegarde full
• Vérification — Version, paramètres et bases · Vérifier le cluster Patroni · Vérifier les logs · Tests applicatifs
• Suppression de l'ancien cluster — Supprimer l'ancien répertoire de données · Supprimer l'ancien répertoire de données sur les …replicas…standbys… · Désinstaller le logiciel de l'ancienne version
• Préparation du serveur source — wal_level = logical · Redémarrer la source · Créer l'utilisateur de réplication · Ajouter la cible dans pg_hba.conf · Recharger pg_hba · Créer la publication
• Schéma et subscription sur la cible — Écrire les mots de passe de la source dans .pgpass · Copier les rôles (globals) · Copier le schéma · Créer la subscription · Attendre la fin de la copie initiale · Vérifier le retard
• Bascule finale (cutover) — Arrêter les écritures sur la source · Vérifier que les dernières modifications ont été transférées · Transférer les valeurs des séquences · Supprimer la subscription · Collecter les statistiques · Rediriger les applications vers la cible …
• Retour arrière — Arrêter le nouveau cluster · Arrêter Patroni sur les replicas · Arrêter Patroni sur le leader · Restaurer pg_control (--link, nouveau cluster non démarré) · …Revenir depuis la sauvegarde (--link, nouveau cluster démarré)…Revenir depuis la sauvegarde logique (--link, nouveau cluster démarré)… · Terminer la recovery sans Patroni …