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

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

Si votre répertoire d'installation n'est pas spécifique à la version, par exemple /usr/local/pgsql, il est nécessaire de déplacer le répertoire d'installation actuelle de PostgreSQL pour qu'il n'interfère pas avec la nouvelle installation de PostgreSQL™. Une fois que le serveur actuel PostgreSQL™ est arrêté, il est bon de renommer le répertoire d'installation de PostgreSQL ; en supposant que l'ancien répertoire est /usr/local/pgsql, vous pouvez saisir ceci :

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

pour renommer le répertoire.

Pour une installation par les sources, construisez la nouvelle version

Construisez la nouvelle version de PostgreSQL avec des options de compilation compatibles avec l'ancienne instance. pg_upgrade utilisera pg_controldata pour vérifier que tous les paramètres sont compatibles avant de lancer la mise à jour.

Installez les nouveaux exécutables de PostgreSQL

Installez les nouveaux exécutables du serveur ainsi que les fichiers de support.

Pour les installations à partir des sources, si vous préférez installer le nouveau serveur dans un emplacement particulier, utilisez le mot clé prefix :

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

Installez pg_upgrade et pg_upgrade_support

Installez l'exécutable pg_upgrade et la bibliothèque pg_upgrade_support dans la nouvelle instance PostgreSQL

Initialisez la nouvelle instance PostgreSQL

Initialisez la nouvelle instance avec initdb. Encore une fois, utilisez des options d'initdb qui correspondent à celles de l'ancienne instance. Beaucoup d'installeurs font cette étape automatiquement. Il n'est pas nécessaire de démarrer la nouvelle instance.

Installez les fichiers objets partagés personnalisés (ou DLL)

Installez tous fichiers objets partagés personnalisés (ou DLL) utilisés par l'ancien cluster dans le nouveau cluster, par exemple pgcrypto.so, qu'ils proviennent des modules contrib ou de toute autre source. N'installez pas les définitions du schéma, par exemple pgcrypto.sql, car elles seront aussi mises à jour à partir de l'ancien cluster.

Ajustez l'authentification

pg_upgrade se connectera à l'ancien et au nouveau serveurs plusieurs fois. Vous devez donc configurer l'authentification ident pour les connexions locales via une socket de domaine Unix ou utiliser un fichier ~/.pgpass (voir Section 31.15, « Fichier de mots de passe »).

Arrêtez les deux serveurs

Assurez-vous que les deux serveurs de bases de données sont stoppés. Pour cela, vous pouvez utiliser la commande suivante sous Unix :

pg_ctl -D /opt/PostgreSQL/8.4 stop
pg_ctl -D /opt/PostgreSQL/9.0 stop

et la commande suivante sous Windows (en utilisant les bons noms de service) :

NET STOP postgresql-8.4
NET STOP postgresql-9.0

ou encore :

NET STOP pgsql-8.3  (PostgreSQL™ 8.3 et antérieurs
utilisent un autre nom de service)

Exécutez pg_upgrade

Exécutez toujours le binaire pg_upgrade dans le nouveau serveur, pas l'ancien. pg_upgrade nécessite de spécifier les repértoires de l'instance (PGDATA) et des exécutables pour l'ancien et la nouvelle instance (bin). Vous pouvez aussi indiquer des valeurs pour l'utilisateur et le port, et si vous voulez que les données soient ajoutées par lien ou par copie (cette dernière étant la valeur par défaut).

Si vous utilisez les liens, la mise à jour sera bien plus rapide (pas de copie de données), mais vous ne serez plus capable d'accéder à votre ancienne instance une fois que vous aurez démarré la nouvelle instance après la mise à jour. Le mode des liens nécessite aussi que les répertoires des données de l'ancienne et de la nouvelle instances soient situés sur le même système de fichiers. Voir pg_upgrade --help pour une liste complète des options.

Pour les utilisateurs Windows, vous devez être connecté avec un compte administrateur, puis lancé un shell en tant qu'utilisateur postgres et configuré la variable PATH correctement :

RUNAS /USER:postgres "CMD.EXE"
SET PATH=%PATH%;C:\Program Files\PostgreSQL\9.0\bin;

Enfin, vous lancez pg_upgrade avec les noms des répertoires entre guillemets doubles, par exemple :

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

Une fois lancé, pg_upgrade vérifiera que les deux instances sont compatibles puis lancera la mise à jour. vous pouvez utiliser pg_upgrade --check pour ne faire que les vérifications, même si l'ancienne installation est en cours d'exécution. pg_upgrade --check indiquera aussi tout ajustement manuel que vous devrez faire après la mise à jour. Si vous utilisez le mode des liens, vous devez utiliser l'option --link avec l'option --check pour activer les tests spécifiques au mode lien. pg_upgrade réclame des droits en écriture dans le répertoire courant.

Évidemment, personne ne doit accéder aux instances pendant la mise à jour. Par défaut, pg_upgrade lance les serveurs sur le port 50432 pour éviter les connexions clientes non désirées. Vous pouvez utiliser le même numéro de port pour chaque instance lors d'une mise à jour car l'ancienne et la nouvelle instance ne seront pas lancées en même temps. Cependant, lors de la vérification d'un ancien serveur en cours d'exécution, l'ancien et le nouveau numéro 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 retourner sur l'ancienne instance comme indiqué dans Étape 14. Pour essayer de nouveau pg_upgrade, vous aurez besoin de modifier l'ancienne instance pour que la restauration du schéma par pg_upgrade réussisse. Si le problème est dû à un module contrib, vous pourriez avoir besoin de désinstaller le module contrib à partir de l'ancienne instance et de l'installer sur la nouvelle après la mise à jour en espérant que le module n'est pas utilisé pour stocker des données de l'utilisateur.

Restaurez pg_hba.conf

Si vous avez modifié pg_hba.conf, restaurez-le à sa configuration d'origine. Il pourrait aussi être nécessaire d'ajuster les autres fichiers de configuration de la nouvelle instance pour correspondre à l'ancienne instance, par exemple le fichier postgresql.conf.

Traitement post-mise à jour

Si tout traitement post-mise à jour est requis, pg_upgrade lancera des avertissements à la fin de son travail. Il générera aussi des fichiers de script à exécuter par l'administrateur. Les fichiers de script se connecteront à chaque base de données pour réaliser un traitement post-mise à jour. Chaque script doit être exécuté avec la commande suivante :

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

Ces scripts peuvent être exécutés dans n'importe quel ordre et peuvent être supprimés une fois qu'ils ont été exécutés.

Attention

En général, il n'est pas prudent d'accéder aux tables référencées dans les scripts de reconstruction tant que ses scripts n'ont pas été exécutés entièrement ; le faire malgré tout pourrait amener des résultats incorrects ou des contre-performances. Les tables non référencées dans les scripts de reconstruction peuvent être utilisées immédiatement.

Statistiques

Attention

Comme les statistiques de l'optimiseur ne sont pas transférées par pg_upgrade, il vous sera demandé d'exécuter une commande pour regénérer les informations statistiques à la fin de la mise à jour.

Supprimez l'ancienne instance

Une fois que vous être satisfait par la mise à jour, vous pouvez supprimer les répertoires de données de l'ancienne instance en exécutant le script mentionné à la fin de pg_upgrade. Vous devrez supprimer manuellement les anciens répertoires d'installation, par exemple bin, share.

Retourner sur l'ancienne instance

Si, après avoir exécuté pg_upgrade, vous souhaitez retourner à l'ancienne instance, il existe plusieurs options.