Si nécessaire, déplacez l'ancienne instance

Si vous utilisez un répertoire d'installation spécifique par version, exemple /opt/PostgreSQL/17, vous n'avez pas besoin de déplacer l'ancienne instance. Les installateurs graphiques utilisent tous des répertoires d'installation spécifiques par version.

Si votre répertoire d'installation n'est pas spécifique par version, par exemple /usr/local/pgsql, il est nécessaire de déplacer le répertoire d'installation courant de PostgreSQL de telle manière à ce qu'il n'interfère pas avec la nouvelle installation de PostgreSQL. Une fois que le serveur courant PostgreSQL est éteint, il est sans danger de renommer le répertoire d'installation de PostgreSQL ; en supposant que l'ancien répertoire est /usr/local/pgsql, vous pouvez faire :

mv /usr/local/pgsql /usr/local/pgsql.old

pour renommer le répertoire.

Pour les installations à partir des sources, construisez la nouvelle version

Construisez la nouvelle version de PostgreSQL à partir des sources avec des options de configure qui sont compatibles avec l'ancienne instance. pg_upgrade utilisera pg_controldata pour s'assurer que l'ensemble des configurations sont compatibles avant de commencer la mise à jour.

Installez les nouveaux binaires PostgreSQL

Installez les binaires du nouveau serveur et les fichiers associés. Par défaut, pg_upgrade est inclus dans une installation.

Pour les installations à partir des sources, si vous souhaitez installer le nouveau serveur dans un répertoire personnalisé, utilisez la variable prefix :

make prefix=/usr/local/pgsql.new install
     

Initialisez la nouvelle instance PostgreSQL

Initialisez la nouvelle instance en utilisant la commande initdb. À nouveau, utilisez des options de la commande initdb compatibles avec l'ancienne instance. Beaucoup d'installateurs pré-construits effectuent cette étape automatiquement. Il n'est pas nécessaire de démarrer la nouvelle instance.

Installez les fichiers objets partagés d'extension

Beaucoup d'extensions et de modules personnalisés, qu'ils viennent de contrib ou d'une autre source, utilisent les fichiers d'objets partagés (ou DLL), par exemple pgcrypto.so. Si l'ancienne instance les utilisait, les fichiers d'objets partagés correspondant aux binaires du nouveau serveur doivent être installés dans la nouvelle instance, habituellement avec les commandes du système d'exploitation. Ne chargez pas les définitions de schéma, par exemple CREATE EXTENSION pgcrypto, parce qu'elles seront dupliquées à partir de l'ancienne instance. Si des mises à jour d'extensions sont disponibles, pg_upgrade l'indiquera et créera un script à exécuter plus tard pour les mettre à jour.

Copiez les fichiers personnalisés de recherche plein texte

Copiez tous les fichiers personnalisés de recherche plein texte (dictionnaire, synonymes, thésaurus, mots d'arrêt) de l'ancienne instance vers la nouvelle.

Ajustez l'authentification

pg_upgrade se connectera à l'ancien et au nouveau serveur plusieurs fois, aussi vous pourriez avoir besoin de positionner l'authentification sur peer ou d'utiliser un fichier ~/.pgpass (voir Section 32.16).

Préparez la mise à jour des publieurs

pg_upgrade essaie de migrer les slots de réplication logique. Cela évite de devoir manuellement définir les mêmes slots logiques sur le nouveau publieur. La migration des slots logiques est seulement supportée lorsque l'ancienne instance à migrer est en version 17.0 ou plus récente. Les slots logiques des instances antérieures à la version 17.0 seront ignorés silencieusement.

Avant de démarrer la mise à jour des publieurs de l'instance, assurez-vous que l'abonnement correspondant est temporairement désactivé, en exécutant ALTER SUBSCRIPTION ... DISABLE. Réactiver l'abonnement après la mise à jour.

Il y a certains prérequis pour que pg_upgrade puisse mettre à jour les slots de réplication logique. Si ceux-ci ne sont pas rencontrés, une erreur sera rapportée.

Préparez la mise à jour des abonnés

Mettre en place les configurations des abonnés sur le nouvel abonné. pg_upgrade tente de migrer les dépendances de l'abonnement, ce qui inclut les informations des tables de l'abonnement présentes dans le catalogue système pg_subscription_rel ainsi que l'origine de réplication de l'abonnement. Cela permet à la réplication logique sur le nouvel abonné de reprendre là où l'ancien abonné s'était arrêté. La migration des dépendances de l'abonnement n'est prise en charge que lorsque l'ancienne instance est en version 17.0 ou ultérieure. Les dépendances des abonnements des instances antérieures à la version 17.0 seront ignorées silencieusement.

Il y a certains prérequis pour que pg_upgrade puisse mettre à jour les abonnements. Si ceux-ci ne sont pas rencontrés, une erreur sera rapportée.

Arrêtez les deux serveurs

Assurez vous que les deux serveurs sont arrêtés en utilisant, sur Unix par exemple :

pg_ctl -D /opt/PostgreSQL/12 stop
pg_ctl -D /opt/PostgreSQL/17 stop
     

ou sur Windows, en utilisant les noms de services corrects :

NET STOP postgresql-12
NET STOP postgresql-17
     

Les serveurs secondaires par réplication en flux et par copie des journaux doivent être en cours d'exécution jusqu'à une étape ultérieure.

Préparez la mise à jour d'un serveur secondaire

Si vous êtes en train de mettre à jour des serveurs secondaires en suivant la description de la section Étape 13, vérifiez en utilisant pg_controldata sur les anciennes instances primaire et secondaire que les anciens serveurs secondaires sont à jour. Vérifiez que les valeurs de « Latest checkpoint location » correspondent dans toutes les instances. De plus, assurez-vous que le paramètre wal_level ne soit pas configuré avec la valeur minimal dans le fichier de configuration postgresql.conf sur la nouvelle instance primaire.

Lancez pg_upgrade

Lancez toujours le binaire pg_upgrade du nouveau serveur, pas celui de l'ancien. pg_upgrade exige la spécification des anciens et des nouveaux répertoires de données et des exécutables (bin). Vous pouvez aussi indiquer des valeurs pour les utilisateurs et les ports, et si vous voulez que les fichiers de données soient liées ou clonées plutôt que copiées (par défaut ce dernier).

Si vous utilisez le mode lien, la mise à jour sera beaucoup plus rapide (pas de copie de fichiers) et utilisera moins d'espace disque, mais vous ne serez plus en mesure d'accéder à votre ancienne instance une fois que la nouvelle instance sera démarrée après la mise à jour. Le mode lien exige également que le répertoire de données de l'ancienne et de la nouvelle instance soient dans le même système de fichiers. (Les tablespaces et pg_wal peuvent être sur des systèmes de fichiers différents.) Le mode de clonage fournit les mêmes avantages au niveau vitesse et espace disque mais ne rend pas l'ancienne instance inutilisable une fois que la nouvelle instance a été démarrée. Le mode de clonage requiert aussi que les répertoires de données de l'ancienne et la nouvelle instances soient dans le même système de fichiers. Ce mode est seulement disponible sur certains systèmes d'exploitation et certains systèmes de fichiers.

L'option --jobs permet l'utilisation de plusieurs cœurs CPU pour copier ou lier des fichiers, et pour sauvegarder et recharger les schémas des bases de données en parallèle ; un bon chiffre pour commencer est le maximum du nombre de cœurs CPU et des tablespaces. Cette option peut réduire drastiquement le temps pour mettre à jour un serveur avec plusieurs bases de données s'exécutant sur une machine multiprocesseur.

Pour les utilisateurs Windows, vous devez être connecté avec un compte administrateur, puis lancez pg_upgrade avec les répertoires entre guillemets, par exemple :

pg_upgrade.exe
        --old-datadir "C:/Program Files/PostgreSQL/12/data"
        --new-datadir "C:/Program Files/PostgreSQL/17/data"
        --old-bindir "C:/Program Files/PostgreSQL/12/bin"
        --new-bindir "C:/Program Files/PostgreSQL/17/bin"
     

Une fois démarré, pg_upgrade vérifiera que les deux instances sont compatibles avant d'effectuer la mise à jour. Vous pouvez utiliser pg_upgrade --check pour effectuer uniquement la vérification, y compris si l'ancien serveur est actuellement en fonctionnement. pg_upgrade --check mettra également en évidence les ajustements manuels nécessaires que vous aurez besoin de faire après la mise à jour. Si vous désirez utiliser le mode lien ou le mode clone, vous devriez indiquer l'option --link ou --clone avec l'option --check pour activer les vérifications spécifiques au mode lien. pg_upgrade doit avoir le droit d'écrire dans le répertoire courant.

Évidemment, personne ne doit accéder aux instances pendant la mise à jour. pg_upgrade lance par défaut les serveurs sur le port 50432 pour éviter les connexions non désirées de clients. Vous pouvez utilisez le même numéro de port pour les deux instances lors d'une mise à jour car l'ancienne et la nouvelle instance ne fonctionneront pas en même temps. Cependant, lors de la vérification d'un ancien serveur en fonctionnement, l'ancien et le nouveau numéros de port doivent être différents.

Si une erreur survient lors de la restauration du schéma de la base de données, pg_upgrade quittera et vous devrez revenir à l'ancienne instance comme décrit ci-dessous (Étape 19). Pour réessayer pg_upgrade, vous aurez besoin de modifier l'ancienne instance de telle manière que la restauration du schéma par pg_upgrade réussisse. Si le problème est un module contrib, vous pourriez avoir besoin de désinstaller le module contrib de l'ancienne instance et le réinstaller dans la nouvelle instance après la mise à jour, en supposant que le module n'est pas utilisé pour stocker des données utilisateur.

Mettez à jour les serveurs secondaires par réplication en flux ou par copie de journaux de transactions

Si vous utilisez le mode lien et avez des serveurs secondaires par réplication continue (voir Section 26.2.5) ou par copie des journaux de transactions (voir Section 26.2), vous pouvez suivre les étapes ci-dessous pour les mettre à jour rapidement. Vous ne lancerez pas pg_upgrade sur les serveurs secondaires, mais plutôt rsync sur le primaire. Ne démarrez encore aucun serveur.

Si vous n'utilisez pas le mode lien, n'avez pas ou ne voulez pas utiliser rsync, ou si vous voulez une solution plus simple, ignorez les instructions de cette section et recréez simplement les serveurs secondaires une fois que pg_upgrade a terminé et que le nouveau primaire fonctionne de nouveau.

Restaurez pg_hba.conf

Si vous avez modifié pg_hba.conf, restaurez cette configuration d'origine. Il peut être aussi nécessaire d'ajuster d'autres fichiers de configuration dans la nouvelle instance pour correspondre à l'ancienne instance, par exemple postgresql.conf (et tout fichier qu'il inclut), postgresql.auto.conf.

Démarrez le nouveau serveur

Le nouveau serveur peut maintenant être démarré en toute sécurité, puis les autres serveurs secondaires synchronisés avec rsync.

Traitements après mise à jour

Si des traitements après mise à jour sont nécessaires, pg_upgrade affichera des avertissements lors de son travail. Il générera également des scripts qui devront être lancés par l'administrateur. Les scripts se connecteront à chaque base de données qui ont besoin de traitements après mise à jour. Chaque script devrait être lancé comme suit :

psql --username=postgres --file=script.sql postgres
     

Les scripts peuvent être lancés dans n'importe quel ordre et détruits une fois terminés.

Statistiques

Parce que les statistiques de l'optimiseur ne sont pas transférées par pg_upgrade, vous serez invités à lancer une commande pour regénérer les statistiques à la fin de la mise à jour. Vous pourriez avoir besoin de positionner les paramètres de connexion pour qu'ils correspondent à votre nouvelle instance.

Utiliser vacuumdb --all --analyze-only peut efficacement générer de telles statistiques, et l'utilisation de --jobs peut l'accélérer. L'option --analyze-in-stages peut être utilisée pour générer des statistiques minimales rapidement. Si vacuum_cost_delay est positionné à une valeur différente de zéro, cela peut être outrepassé pour accélérer la génération des statistiques en utilisant PGOPTIONS, par exemple, PGOPTIONS='-c vacuum_cost_delay=0' vacuumdb ....

Détruire les anciennes instances

Une fois que vous êtes satisfait de la mise à jour, vous pouvez détruire les répertoires de données des anciennes instances en lançant le script indiqué par pg_upgrade à la fin de son traitement. (La destruction automatique n'est pas possible si vous avez défini des tablespaces personnalisés dans l'ancien répertoire de données.) Vous pouvez également supprimer les anciens répertoires d'installation (par exemple bin, share).

Revenir à l'ancienne instance

Si, après avoir lancé pg_upgrade, vous désirez revenir à l'ancienne instance, il y a plusieurs options :