Installer et configurer PostgreSQL sur Debian et Ubuntu

PostgreSQL s'installe en deux minutes sur Debian et Ubuntu. Les deux heures qui suivent partent en général dans un seul problème : personne n'arrive à se connecter. Cet article va au bout de l'installation : choix du paquet, premier accès, base de données et utilisateur, les règles d'accès dans pg_hba.conf et une sauvegarde dont vous savez qu'elle se restaure vraiment.

Toutes les commandes s'exécutent en tant que root. Si vous êtes connecté avec un compte normal, préfixez-les par sudo. Le numéro de version 17 dans les chemins est à remplacer par la version réellement installée sur votre système.

Quelle version de PostgreSQL dans quelle distribution

La différence la plus importante entre les quatre systèmes courants tient à la version majeure fournie par le dépôt de la distribution. Elle est figée avec la publication de la version et ne change plus pendant toute la durée de vie de la distribution.

Cette dispersion a des conséquences très concrètes. Un dump produit sous Debian 13 ne se restaure pas tel quel sous Ubuntu 22.04. Et si vous travaillez sous Ubuntu 22.04, sachez que PostgreSQL 14 sort du support communautaire le 12 novembre 2026, conformément à la politique de versionnement du PostgreSQL Global Development Group. Ubuntu continue certes de livrer des mises à jour de sécurité pour 22.04 dans le cadre du cycle LTS, mais plus aucun correctif upstream n'est repris. Pour un nouveau projet sur 22.04, c'est un argument sérieux en faveur du dépôt PGDG dès le départ.

Avant d'installer quoi que ce soit, un coup d'œil dans la base de paquets vous dit ce qui est disponible sur votre système :

apt update
apt-cache policy postgresql

La ligne Candidat, ou Candidate sur un système anglophone, affiche un numéro de version comme 17+283. Le nombre avant le signe plus est la version majeure de PostgreSQL, le reste est le numéro de version du métapaquet Debian.

Installer depuis le paquet de la distribution

Dans la plupart des cas, le paquet de la distribution est le bon choix. Il est intégré aux mises à jour de sécurité du système, il fonctionne avec les bibliothèques présentes et il ne pose aucun problème lors d'une montée de version de la distribution.

apt install -y postgresql postgresql-contrib

postgresql-contrib apporte les extensions livrées avec le serveur, dont pgcrypto, uuid-ossp et pg_stat_statements. Sans ce paquet, beaucoup d'applications échouent plus tard sur un ERROR: could not open extension control file, et le diagnostic prend plus de temps que l'installation elle-même.

À l'installation, Debian et Ubuntu créent automatiquement un premier cluster nommé main et le démarrent. Un cluster désigne ici une instance en cours d'exécution, avec son propre répertoire de données, son propre port et sa propre configuration. Ce n'est pas le code de retour d'apt qui vous dit si l'opération a réussi, mais ceci :

pg_lsclusters

La colonne Status doit afficher online :

Ver Cluster Port Status Owner    Data directory              Log file
17  main    5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log

Si vous y lisez down, démarrez le service. service postgresql start fonctionne sur les quatre systèmes, y compris dans un conteneur sans systemd. Sur un serveur classique, systemctl start postgresql fait tout aussi bien l'affaire.

service postgresql start
pg_isready

pg_isready répond /var/run/postgresql:5432 - accepting connections et renvoie le code de retour 0. C'est la première preuve tangible que le serveur est joignable, et elle se réutilise telle quelle dans vos scripts de supervision.

Quand le dépôt PGDG vaut le détour et comment l'intégrer proprement

Le dépôt officiel sur apt.postgresql.org fournit en parallèle toutes les versions majeures supportées pour trixie, bookworm, noble et jammy. C'est le bon choix si vous avez besoin d'une version majeure précise parce que l'application l'exige, si vous avez besoin d'extensions que Debian ne fournit pas en paquet, ou si l'état de votre distribution pointe vers une version dont le support s'arrête bientôt.

La clé va dans un fichier dédié, et non plus dans le trousseau apt-key, qui est déprécié. Debian 13 et Ubuntu 24.04 privilégient par ailleurs le format deb822 avec l'extension .sources, qui fonctionne pourtant aussi sur Debian 12 et Ubuntu 22.04 :

apt install -y curl ca-certificates
install -d /usr/share/postgresql-common/pgdg
curl -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc

cat > /etc/apt/sources.list.d/pgdg.sources <<EOF
Types: deb
URIs: https://apt.postgresql.org/pub/repos/apt
Suites: $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg
Components: main
Signed-By: /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
EOF

La ligne contenant $(. /etc/os-release ...) insère automatiquement trixie-pgdg, bookworm-pgdg, noble-pgdg ou jammy-pgdg. Ensuite :

apt update
apt-cache policy postgresql-18

Le paquet postgresql-common fournit un script tout prêt pour le même usage, /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh. C'est une alternative à la clé et au fichier pgdg.sources ci-dessus, pas un complément. Si vous exécutez les deux, le script crée en plus un fichier /etc/apt/sources.list.d/pgdg.list, et apt vous avertit ensuite à chaque exécution : W: Target Packages (main/binary-amd64/Packages) is configured multiple times in /etc/apt/sources.list.d/pgdg.list:1 and /etc/apt/sources.list.d/pgdg.sources:1. Si vous préférez le script aux manipulations ci-dessus, installez gnupg en même temps, donc apt install -y curl ca-certificates gnupg. La version plus ancienne du script sur Ubuntu 22.04 importe en effet encore la clé via apt-key et s'arrête sans gnupg sur E: gnupg, gnupg2 and gnupg1 do not seem to be installed, but one of them is required for this operation, avec le code de retour 255. Sur Debian 13, Debian 12 et Ubuntu 24.04, la version plus récente dépose la clé directement au format .asc et s'exécute sans paquet supplémentaire.

Le piège : deux clusters, deux ports

Si vous installez maintenant une nouvelle version majeure sur un système où le paquet de la distribution est déjà présent, un second cluster apparaît. Il ne reçoit pas le port 5432, mais le suivant qui est libre, donc 5433. Les applications continuent de se connecter à l'ancienne version, sans le moindre message d'erreur pour le signaler. C'est la cause la plus fréquente de la phrase « j'ai pourtant installé PostgreSQL 18, mais SELECT version() affiche 15 ».

apt install -y postgresql-18
pg_lsclusters

Deux lignes apparaissent alors, avec des ports différents. Si vous voulez reprendre les données dans la nouvelle version, l'outil adapté est pg_upgradecluster, pas un dump fait à la main. Il exige que les deux paquets serveur soient installés, et il laisse l'ancien cluster en place, arrêté, au lieu de le supprimer :

pg_upgradecluster 15 main

Vérifiez ensuite avec pg_lsclusters quel cluster occupe le port 5432, et testez l'application avant de supprimer définitivement l'ancien cluster avec pg_dropcluster --stop 15 main. Cette commande efface le répertoire de données sans demander confirmation.

Le premier accès, et pourquoi root n'a pas le droit d'utiliser psql

L'obstacle classique, juste après l'installation :

psql: error: connection to server on socket "/var/run/postgresql/.s.PGSQL.5432" failed: FATAL:  role "root" does not exist

Ce n'est pas un bug, c'est le comportement attendu. Debian et Ubuntu configurent les connexions locales par socket avec la méthode peer. PostgreSQL demande alors au noyau sous quel utilisateur système la connexion a été ouverte, et exige qu'il existe un rôle de base de données du même nom. Seul le rôle postgres existe, vous devez donc d'abord basculer sur cet utilisateur système.

su - postgres

Vous lancez ensuite psql sans argument. Pour quitter le shell, tapez exit. Pour des commandes isolées lancées depuis un script, un changement d'utilisateur par commande est plus pratique :

runuser -u postgres -- psql -c "SELECT version();"

Si sudo est installé, écrivez plutôt sudo -u postgres psql -c "SELECT version();". Les deux variantes se valent. Avec sudo, l'avertissement could not change directory to "/root": Permission denied apparaît souvent. Il est sans conséquence, car l'utilisateur postgres n'a pas le droit d'entrer dans le répertoire de travail de root, alors que la commande s'exécute quand même.

Ces trois requêtes vous disent à quoi vous avez affaire, et elles constituent la première étape de tout diagnostic :

runuser -u postgres -- psql -c "SHOW server_version;"
runuser -u postgres -- psql -c "SHOW config_file;"
runuser -u postgres -- psql -c "SHOW hba_file;"

La dernière commande est particulièrement utile. Elle donne le chemin que le serveur en cours d'exécution lit réellement, typiquement /etc/postgresql/17/main/pg_hba.conf. Si vous modifiez un fichier et que rien ne change, vous avez presque toujours sous les yeux la configuration d'un autre cluster.

Dans psql, les méta-commandes aident : \l liste les bases de données, \du les rôles, \dt les tables de la base courante, \conninfo montre en tant que qui et où vous êtes connecté, et \q termine la session.

Créer la base de données et l'utilisateur

Chaque application mérite son propre rôle et sa propre base de données. L'ordre compte, car la base doit appartenir directement au rôle.

runuser -u postgres -- psql -c "CREATE ROLE appuser LOGIN PASSWORD 'VotreMotDePasseFort';"
runuser -u postgres -- psql -c "CREATE DATABASE appdb OWNER appuser;"

Depuis PostgreSQL 14, les mots de passe sont enregistrés par défaut avec scram-sha-256 : c'est donc le cas sur les quatre systèmes traités ici. Le mot de passe n'arrive pas en clair dans la base, mais il reste dans l'historique de votre shell. Pour éviter cela, utilisez plutôt \password appuser dans psql, qui le demande de façon interactive.

Le piège depuis PostgreSQL 15 : permission denied for schema public

Un comportement que beaucoup de tutoriels anciens ignorent encore : à partir de PostgreSQL 15, tout utilisateur n'a plus le droit de créer des objets dans le schéma public. Sont concernés Debian 12, Debian 13 et Ubuntu 24.04. Seul Ubuntu 22.04 avec PostgreSQL 14 se comporte encore à l'ancienne. L'erreur ressemble à ceci :

ERROR:  permission denied for schema public
LINE 1: CREATE TABLE clients (id serial primary key);

La voie propre est celle montrée plus haut : la base de données appartient au rôle. Depuis la version 15, le schéma public appartient au rôle pg_database_owner, et le propriétaire de la base en est membre implicite. Si vous avez créé la base sans OWNER, accordez le droit après coup. Attention, cette instruction doit être exécutée dans la base concernée, pas dans postgres :

runuser -u postgres -- psql -d appdb -c "GRANT ALL ON SCHEMA public TO appuser;"

La preuve que les droits sont corrects

Un CREATE ROLE sans erreur ne signifie pas encore que l'application pourra se connecter. La preuve, c'est une vraie connexion en TCP suivie d'un accès en écriture. PGPASSWORD n'est ici destiné qu'au test, pour l'exploitation courante voyez plus bas :

PGPASSWORD='VotreMotDePasseFort' psql -h 127.0.0.1 -U appuser -d appdb -c "SELECT current_user, current_database();"
PGPASSWORD='VotreMotDePasseFort' psql -h 127.0.0.1 -U appuser -d appdb -c "CREATE TABLE essai (id int);"

Si les deux passent, la combinaison rôle, mot de passe, base de données et droits sur le schéma est complète. La table essai reste volontairement en place, car le test de sauvegarde plus bas a besoin d'au moins un objet dans la base, sinon il ne vérifie rien du tout. Pour contrôler, listez les objets :

runuser -u postgres -- psql -c "\du"
runuser -u postgres -- psql -c "\l"

Un mot sur l'encodage des caractères : si la locale du système n'était pas en UTF-8 au moment de la création du cluster, la base modèle peut être en SQL_ASCII. Un CREATE DATABASE ... ENCODING 'UTF8' échoue alors avec ERROR: new encoding (UTF8) is incompatible with the encoding of the template database (SQL_ASCII). Le contournement consiste à préciser TEMPLATE template0 à la création, la solution propre reste un système avec une locale UTF-8.

Comprendre pg_hba.conf, la source d'erreurs la plus fréquente

Le fichier pg_hba.conf (host-based authentication) décide, avant toute vérification de mot de passe, si une connexion est acceptée. Il est lu de haut en bas, et la première ligne qui correspond l'emporte. Si aucune ne correspond, la connexion est refusée. Une règle permissive placée plus bas ne vous sert à rien si une règle plus stricte s'applique avant elle. C'est de loin l'erreur de configuration la plus courante.

L'état livré par défaut sur Debian et Ubuntu se présente ainsi :

# TYPE  DATABASE        USER            ADDRESS                 METHOD
local   all             postgres                                peer
local   all             all                                     peer
host    all             all             127.0.0.1/32            scram-sha-256
host    all             all             ::1/128                 scram-sha-256

C'est ce que l'on trouve sur les quatre systèmes traités ici. Sur des versions plus anciennes, par exemple Debian 11 avec PostgreSQL 13, les deux lignes host portent encore md5 au lieu de scram-sha-256. La connexion en TCP fonctionne dans les deux cas, mais vous ne devriez plus compter sur md5.

Signification des colonnes : local désigne le socket Unix, host le TCP avec ou sans TLS, hostssl uniquement les connexions TLS. Viennent ensuite la base de données, le rôle, la plage réseau en notation CIDR et la méthode. Quatre méthodes comptent vraiment. peer vérifie l'utilisateur système et ne fonctionne qu'à travers le socket. scram-sha-256 est la méthode moderne par mot de passe et le bon choix pour tout ce qui passe par TCP. md5 est déprécié et n'a plus sa place dans une configuration neuve. trust laisse entrer n'importe qui sans contrôle et n'a rien à faire sur un serveur joignable.

Les messages d'erreur, mot pour mot

Savoir les distinguer une bonne fois vous épargne beaucoup de suppositions :

FATAL:  Peer authentication failed for user "appuser"

Vous êtes connecté par le socket, mais votre utilisateur système ne porte pas le même nom que le rôle. Changez d'utilisateur, ou connectez-vous via -h 127.0.0.1 pour que la ligne host s'applique.

FATAL:  no pg_hba.conf entry for host "198.51.100.4", user "appuser", database "appdb", no encryption

Le serveur est joignable, mais aucune règle ne correspond à cette combinaison d'adresse source, de rôle et de base de données. Il manque une ligne, ou le réseau indiqué dans la ligne existante ne couvre pas l'adresse.

FATAL:  password authentication failed for user "appuser"

La règle s'applique, le mot de passe est faux. Souvent parce que le rôle a été créé sans LOGIN, ou parce que le mot de passe date d'une installation antérieure.

psql: error: connection to server at "203.0.113.10", port 5432 failed: Connection refused

Ici, pg_hba.conf n'est jamais entré en jeu. Soit le serveur ne tourne pas, soit il n'écoute pas sur cette adresse, soit un pare-feu bloque. Nous y revenons juste après.

Vérifier les modifications avant de recharger

PostgreSQL propose une vue système qui montre les règles telles qu'elles ont été analysées, avec le numéro de ligne et les erreurs de syntaxe. Elle répond à la question de savoir quelle règle le serveur voit réellement, et non celle que vous croyez avoir écrite :

runuser -u postgres -- psql -c "SELECT line_number, type, database, user_name, address, auth_method FROM pg_hba_file_rules;"

Les modifications de pg_hba.conf ne demandent aucun redémarrage, un rechargement suffit et ne coupe aucune connexion existante :

runuser -u postgres -- psql -c "SELECT pg_reload_conf();"

Autre possibilité, service postgresql reload. Un vrai redémarrage n'est nécessaire que si vous avez modifié des paramètres comme listen_addresses, port ou shared_buffers.

Ouvrir l'accès depuis l'extérieur

Par défaut, PostgreSQL n'écoute que sur localhost. C'est un bon réglage, et vous ne devriez y renoncer que si c'est vraiment nécessaire. Deux conditions doivent être réunies : le serveur doit écouter sur l'adresse, et pg_hba.conf doit autoriser la source. S'il manque la première, vous obtenez Connection refused, s'il manque la seconde, vous obtenez no pg_hba.conf entry.

La configuration se trouve dans /etc/postgresql/17/main/postgresql.conf. Debian fournit pour cela l'outil pg_conftool, qui modifie le fichier de façon plus fiable qu'un rechercher/remplacer dans un éditeur :

pg_conftool 17 main show listen_addresses
pg_conftool 17 main set listen_addresses '10.0.0.5,127.0.0.1'

Indiquez des adresses précises plutôt qu'un *. Sur un serveur doté d'une adresse publique et d'une adresse interne, vous ne vous liez ainsi qu'au réseau interne. Ajoutez ensuite une règle dans pg_hba.conf, aussi restrictive que possible :

host    appdb    appuser    10.0.0.0/24    scram-sha-256

Après un redémarrage avec service postgresql restart, vérifiez d'abord sur quoi le processus écoute réellement. ss -lntp | grep 5432 montre les adresses liées. S'il n'y figure que 127.0.0.1:5432, la modification n'a pas pris effet, le plus souvent parce qu'elle visait un autre cluster ou parce qu'un fichier sous conf.d écrase la valeur.

Le pare-feu a lui aussi besoin d'une règle, et d'une règle avec indication de source. Un port 5432 ouvert sans restriction sur Internet est scanné en quelques heures :

ufw allow from 10.0.0.0/24 to any port 5432 proto tcp

Un conseil honnête : dans la plupart des cas, la meilleure solution consiste à ne pas ouvrir le port du tout. Un tunnel SSH avec ssh -L 5432:127.0.0.1:5432 utilisateur@serveur suffit largement pour les accès de maintenance. Pour des connexions permanentes entre plusieurs serveurs, un réseau WireGuard est le choix le plus propre, car la base de données continue alors d'écouter uniquement sur une adresse privée. Debian et Ubuntu activent d'ailleurs TLS par défaut avec un certificat auto-signé, c'est pourquoi sslmode=require fonctionne immédiatement. Mais seule l'option sslmode=verify-full, avec un certificat auquel le client fait confiance, protège réellement contre un attaquant placé sur le chemin.

Sauvegarder avec pg_dump, et prouver que la sauvegarde vaut quelque chose

Pour une base de données isolée, le format custom est le meilleur choix. Il est compressé, il se restaure de façon sélective et il peut être relu en parallèle :

runuser -u postgres -- pg_dump -Fc -d appdb -f /var/lib/postgresql/appdb.dump

Un point souvent oublié : pg_dump ne sauvegarde ni les rôles ni les mots de passe. Ceux-ci existent au niveau du cluster et doivent être sauvegardés séparément, faute de quoi il manquera après une restauration précisément les utilisateurs dont l'application a besoin :

runuser -u postgres -- pg_dumpall --globals-only -f /var/lib/postgresql/globals.sql

Quand les versions ne correspondent pas

pg_dump: error: server version: 17.5; pg_dump version: 15.10
pg_dump: error: aborting because of server version mismatch

La règle est la suivante : pg_dump peut être plus récent que le serveur, jamais plus ancien. Sur Debian et Ubuntu, cela se règle facilement, car /usr/bin/pg_dump n'est qu'un wrapper qui choisit la version de programme adaptée. Installez le paquet postgresql-client-18 et la version plus récente sera disponible. Et avec l'extension Debian --cluster, vous forcez le wrapper sur un cluster précis, ici la version 17, cluster main :

pg_dump --version
runuser -u postgres -- pg_dump --cluster 17/main -Fc -d appdb -f /var/lib/postgresql/appdb.dump

Garder les mots de passe hors des scripts

Pour des sauvegardes automatiques, le mot de passe a sa place dans un fichier .pgpass, au format hote:port:base:utilisateur:motdepasse. PostgreSQL ignore ce fichier sans le moindre message si ses droits sont trop larges. Le répertoire personnel dans lequel il se trouve compte tout autant, car c'est toujours le fichier de l'utilisateur qui exécute réellement la commande qui est lu. Un ~/.pgpass créé en tant que root reste sans effet tant que la sauvegarde passe par runuser -u postgres, comme dans cet article. C'est alors le répertoire personnel de postgres qui compte :

touch /var/lib/postgresql/.pgpass
chown postgres:postgres /var/lib/postgresql/.pgpass
chmod 0600 /var/lib/postgresql/.pgpass

Un fichier vide reste tout aussi inopérant. Saisissez une ligne par connexion, par exemple 127.0.0.1:5432:appdb:appuser:VotreMotDePasseFort. Si votre tâche de sauvegarde s'exécute directement en tant que root, sans changement d'utilisateur, le même fichier va dans /root/.pgpass.

Vérifier la sauvegarde

Un fichier de sauvegarde jamais restauré n'est qu'une hypothèse. Le test prend une minute. Regardez d'abord la table des matières, puis relisez le fichier dans une base de données jetable et comptez les tables :

runuser -u postgres -- pg_restore -l /var/lib/postgresql/appdb.dump | head -n 20
runuser -u postgres -- createdb appdb_restore_test
runuser -u postgres -- pg_restore -d appdb_restore_test /var/lib/postgresql/appdb.dump
runuser -u postgres -- psql -d appdb_restore_test -c "\dt"
runuser -u postgres -- dropdb appdb_restore_test

Si \dt montre les mêmes tables que dans l'original, ici au moins la table essai, la sauvegarde est exploitable. Si la commande répond en revanche Did not find any relations., la base sauvegardée était vide et le test ne prouve rien. Dans appdb, vous supprimez ensuite la table de test avec runuser -u postgres -- psql -d appdb -c "DROP TABLE essai;". Pour l'exploitation quotidienne, une entrée dans /etc/cron.d suffit : elle dépose les deux fichiers avec la date dans le nom et fait le ménage dans les anciens. L'important, c'est que les fichiers quittent ensuite le serveur. Une sauvegarde posée sur le même disque protège contre un DROP TABLE malencontreux, pas contre une panne matérielle.

Quand le cluster ne démarre pas

Si le service ne démarre pas, son état vous indique en général seulement que quelque chose a échoué. La véritable cause se trouve dans le log du cluster :

tail -n 30 /var/log/postgresql/postgresql-*-main.log

Il y a une ligne que vous pouvez tranquillement passer. Le message FATAL: role "root" does not exist, déjà rencontré dans la première section, provient le plus souvent de pg_isready : l'outil construit sa tentative de connexion avec l'utilisateur système connecté, donc root, et le serveur consigne ce rôle inconnu. Le code de retour reste malgré tout 0, la sortie indique accepting connections, et le cluster se porte parfaitement bien.

Sur les systèmes avec systemd, journalctl -u postgresql@17-main --no-pager -n 50 fournit les mêmes lignes. Attention à l'unité qui porte le numéro de version : postgresql.service n'est qu'une enveloppe qui démarre tous les clusters, et elle signale un succès même lorsqu'un cluster isolé a échoué. C'est pourquoi pg_lsclusters reste le contrôle le plus fiable.

Trois messages couvrent la majorité des cas. could not bind IPv4 address "0.0.0.0": Address already in use signifie qu'un autre cluster occupe le port, voyez la section sur les deux clusters. Un message No space left on device lors de l'écriture du fichier postmaster.pid veut simplement dire que le disque est plein, ce que vous confirmez avec df -h. Et les erreurs de droits sur le répertoire de données apparaissent après des chmod ou des chown lancés sans précaution : /var/lib/postgresql/17/main doit appartenir à l'utilisateur postgres et porter le mode 0700.

Pour finir, un mot sur l'exploitation : dans sa configuration par défaut, PostgreSQL reste conservateur et n'exploite de loin pas toute la mémoire d'un serveur. Avant de toucher à shared_buffers et work_mem, activez pg_stat_statements du paquet contrib et regardez quelles requêtes coûtent réellement du temps. En pratique, le goulot d'étranglement vient presque toujours d'un index manquant, pas des paramètres mémoire.