Docker pgAdmin : comment configurer une interface graphique PostgreSQL avec Docker Compose

Passer d'une session à l'autre, retenir la syntaxe et espérer ne pas avoir tapé une requête destructrice avec une faute de frappe : cela devient vite lassant. Pas de plan d'exécution visuel, pas d'explorateur de schéma, et aucune façon simple de sauvegarder une base. Ça fonctionne, mais on est loin de l'idéal.

pgAdmin 4 résout ces problèmes avec une interface web conçue spécialement pour PostgreSQL. Et l'exécuter dans Docker signifie zéro installation locale : il suffit de démarrer le conteneur.

Dans cet article, je vous montre comment configurer PostgreSQL et pgAdmin 4 avec Docker Compose, connecter les deux conteneurs, puis utiliser le Query Tool, l'explorateur de schéma et les fonctionnalités de sauvegarde de pgAdmin.

Pour suivre, vous devez avoir Docker installé et en cours d'exécution sur votre machine. Si vous débutez avec Docker Compose, consultez notre guide pour voir comment il simplifie le développement multi-conteneurs.

Qu'est-ce que pgAdmin 4 ?

pgAdmin 4 est une plateforme open source d'administration et de développement pour PostgreSQL, accessible depuis un navigateur. Aucune application de bureau à installer. Vous disposez d'une interface graphique pour gérer vos bases, exécuter des requêtes, inspecter les schémas et gérer les sauvegardes – sans passer par la ligne de commande.

L'image Docker officielle est dpage/pgadmin4, maintenue par l'équipe de développement de pgAdmin.

Exécuter pgAdmin 4 dans Docker présente plusieurs avantages réels par rapport à une installation locale. D'abord, la portabilité : tout votre environnement base de données tient dans un fichier docker-compose.yml partageable avec vos équipes. Ensuite, pas de conflits de versions : pgAdmin tourne dans son propre conteneur, entièrement isolé du reste de votre machine. Et quand vous avez terminé, docker compose down nettoie tout.

pgAdmin 4 vs autres interfaces graphiques PostgreSQL

Les outils d'administration de bases de données ne manquent pas. Voici comment pgAdmin 4 se compare à deux alternatives populaires.

pgAdmin 4 face aux alternatives populaires

DBeaver et TablePlus sont d'excellents outils, mais aucun ne propose d'image Docker officielle. Si votre instance PostgreSQL tourne déjà dans Docker, pgAdmin 4 est idéal : ajoutez simplement un service à votre docker-compose.yml et l'ensemble fonctionne dans le même réseau.

Mise en place de l'environnement avec Docker Compose

La façon la plus rapide de lancer PostgreSQL et pgAdmin 4 ensemble est d'utiliser un unique fichier docker-compose.yml. Si vous débutez, notre guide Docker Compose couvre les fondamentaux. Ici, je me concentre sur la configuration propre à pgAdmin.

Voici le fichier complet à copier-coller :

services:
  postgres:
    image: postgres:18
    container_name: postgres
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: mydb
    volumes:
      - postgres_data:/var/lib/postgresql
    networks:
      - pgnetwork

  pgadmin:
    image: dpage/pgadmin4:9.13
    container_name: pgadmin
    environment:
      PGADMIN_DEFAULT_EMAIL: you@yourdomain.com
      PGADMIN_DEFAULT_PASSWORD: password
      PGADMIN_LISTEN_PORT: 5050 
    ports:
      - "5050:5050"                
    volumes:
      - pgadmin_data:/var/lib/pgadmin
    depends_on:
      - postgres
    networks:
      - pgnetwork

volumes:
  postgres_data:
  pgadmin_data:

networks:
  pgnetwork:

Le champ depends_on indique à Docker Compose de démarrer le conteneur postgres avant pgadmin. Sans cela, pgAdmin pourrait démarrer avant que PostgreSQL soit prêt et échouer à se connecter. Il n'attend pas que PostgreSQL soit pleinement « healthy » : seulement que le conteneur soit lancé. C'est suffisant pour éviter la plupart des conditions de course.

Variables d'environnement de pgAdmin 4

Deux variables d'environnement sont obligatoires :

• PGADMIN_DEFAULT_EMAIL : l'adresse e-mail utilisée pour vous connecter à l'interface web de pgAdmin
• PGADMIN_DEFAULT_PASSWORD : le mot de passe de ce compte

Une troisième est facultative, mais recommandée :

• PGADMIN_LISTEN_PORT : le port écouté par pgAdmin dans le conteneur. Par défaut : 80, mais le fixer à 5050 simplifie la gestion des mappages de ports.

Cela dit, coder en dur des identifiants dans le fichier Compose est une mauvaise idée, surtout s'il finit sous contrôle de version. Déplacez-les dans un fichier .env.

Créez un fichier .env dans le même répertoire que votre docker-compose.yml :

POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=mydb
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=secret

Référencez ensuite ces variables dans votre fichier Compose :

# postgres
environment:
  POSTGRES_USER: ${POSTGRES_USER}
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
  POSTGRES_DB: ${POSTGRES_DB}
  
# pgadmin
environment:
  PGADMIN_DEFAULT_EMAIL: ${PGADMIN_DEFAULT_EMAIL}
  PGADMIN_DEFAULT_PASSWORD: ${PGADMIN_DEFAULT_PASSWORD}

Docker Compose charge automatiquement les fichiers .env à l'exécution, sans configuration supplémentaire. Pensez simplement à ajouter .env à votre .gitignore pour garder les identifiants hors du dépôt.

Volumes et persistance des données

Le volume monté sur /var/lib/pgadmin est l'endroit où pgAdmin conserve ses données : sessions, connexions enregistrées, configuration. Si vous le supprimez du fichier Compose, vous perdrez tout à chaque redémarrage du conteneur.

Dans la configuration actuelle, vous utilisez un volume nommé géré par Docker sur votre hôte. Les données survivent aux redémarrages, à la recréation des conteneurs et aux mises à jour d'images – tant que vous ne supprimez pas explicitement le volume avec docker volume rm.

Démarrer la stack et accéder à pgAdmin 4

Avec votre docker-compose.yml prêt, un simple commande lance la stack :

docker compose up -d

L'option -d exécute les deux conteneurs en mode détaché : ils tournent en arrière-plan et votre terminal reste disponible. Pour vérifier qu'ils s'exécutent bien :

docker ps

Vous devriez voir postgres et pgadmin avec un statut Up.

Statut des conteneurs

En cas d'anomalie, consultez les logs de pgAdmin :

docker logs pgadmin

Un démarrage sain ressemble à ceci :

Logs de démarrage de pgAdmin

Si vous voyez une erreur, il s'agira probablement de l'un de ces trois cas :

• Échec d'authentification par mot de passe : votre PGADMIN_DEFAULT_PASSWORD manque ou est mal formé dans le fichier .env

• Port déjà utilisé : un autre service écoute sur le port 5050 ; modifiez le port hôte dans votre fichier Compose

• No such file or directory : le chemin du volume est incorrect ou le conteneur n'a pas les droits d'écriture

Une fois les deux conteneurs lancés et les logs propres, ouvrez votre navigateur et allez sur http://localhost:5050 :

Page de connexion pgAdmin

Connectez-vous avec l'e-mail et le mot de passe définis dans PGADMIN_DEFAULT_EMAIL et PGADMIN_DEFAULT_PASSWORD. Vous arrivez sur le tableau de bord de pgAdmin, prêt à enregistrer votre serveur PostgreSQL :

Page d'accueil pgAdmin

Connecter pgAdmin 4 à votre conteneur PostgreSQL

Dans la barre latérale de pgAdmin, cliquez droit sur Servers – Register – Server. Une boîte de dialogue s'ouvre avec deux onglets à renseigner : General et Connection.

L'onglet General

Donnez un nom parlant à votre serveur – par exemple local-dev-postgres. Ce n'est qu'une étiquette dans pgAdmin, choisissez donc ce qui vous parle.

Enregistrement du serveur – onglet General

L'onglet Connection

N'utilisez pas localhost ici. 

Dans un réseau Docker, localhost désigne le conteneur lui-même – ni votre machine hôte, ni le conteneur PostgreSQL. Docker dispose de son propre DNS interne, qui résout les noms des conteneurs à partir des noms de service définis dans votre docker-compose.yml. Si votre service PostgreSQL s'appelle postgres, c'est ce nom d'hôte qu'il faut utiliser.

Renseignez les champs comme suit :

• Host name/address : postgres (le nom de service du docker-compose.yml)

• Port : 5432

• Maintenance database : la valeur de POSTGRES_DB dans votre Compose (ex. : mydb)

• Username : la valeur de POSTGRES_USER (ex. : admin)

• Password : la valeur de POSTGRES_PASSWORD

Cliquez sur Save.

Enregistrement du serveur – onglet Connection

Si tout est correct, le serveur apparaît dans la barre latérale et vous pourrez le déployer pour afficher vos bases :

Enregistrement du serveur réussi

Cela signifie que la connexion est en place.

Utiliser le Query Tool

Maintenant que vous êtes connecté, passons aux bases de pgAdmin 4 et de Postgres en général.

Ouvrez le Query Tool via Tools – Query Tool dans le menu supérieur. L'interface comporte trois panneaux :

• Editor : pour écrire le SQL
• Data Output : où s'affichent les résultats après exécution
• Messages : où PostgreSQL envoie les statuts, erreurs et infos d'exécution

Query Tool

Rédiger et exécuter du SQL

Créons une table orders simple et ajoutons quelques données. Vous pouvez exécuter chaque bloc via le bouton Lecture ou avec F5 (raccourci).

Exécutez ceci pour créer la table :

CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_name VARCHAR(100) NOT NULL,
    product VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    order_date DATE DEFAULT CURRENT_DATE
);

Insérez quelques lignes :

INSERT INTO orders (customer_name, product, quantity)
VALUES
    ('Alice Johnson', 'Wireless Keyboard', 2),
    ('Bob Smith', 'USB-C Hub', 1),
    ('Carol White', 'Mechanical Keyboard', 3);

Et interrogez maintenant les données :

SELECT * FROM orders;

Interroger les données

Les résultats s'affichent dans le panneau Data Output sous forme de tableau. Vous pouvez trier les colonnes, les redimensionner et copier des lignes directement depuis la grille.

Lire le plan d'exécution visuel

Pour voir ce qui se passe en coulisses lors de l'exécution d'une requête, lancez EXPLAIN ANALYZE sur votre SELECT :

EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_name = 'Alice Johnson';

Résultats d'Explain Analyze

Le panneau Data Output affiche la sortie brute. Mais pgAdmin propose mieux : cliquez sur le bouton Explain dans la barre d'outils pour obtenir un plan sous forme de graphe interactif.

Plan de requête en graphe

Ici, c'est simple, mais si vous faites des jointures ou des agrégations complexes, vous en tirerez beaucoup plus d'enseignements.

C'est important car lire la sortie brute de EXPLAIN est lent et source d'erreurs. Le plan visuel rend évident un scan séquentiel sur une grande table, ou un index existant mais non utilisé.

Gérer votre schéma de base de données

La barre latérale de pgAdmin offre une vue complète de la structure de votre base – et permet de la modifier via l'interface.

L'arborescence est : Servers – votre serveur – Databases – votre base – Schemas – public – Tables. Déployez une table pour voir ses Columns, Indexes et Constraints comme nœuds enfants. Cliquez pour afficher les détails à droite.

Créer et modifier des tables

Pour créer une table, cliquez droit sur Tables dans votre schéma puis Create – Table. Une boîte de dialogue s'ouvre avec plusieurs onglets.

Création de tables

L'onglet General sert à nommer la table. Passez à l'onglet Columns pour ajouter vos colonnes : nom, type de données, longueur, nullabilité. L'onglet Constraints gère clés primaires, étrangères et contraintes d'unicité.

Pour ajouter un index à une table existante, déployez-la, cliquez droit sur Indexes, puis Create – Index. Choisissez les colonnes et le type d'index : btree par défaut convient dans la majorité des cas.

Création d'un index

Sauvegarde et restauration

Pour sauvegarder une base, allez dans Tools – Backup. Vous devrez choisir un format :

• Custom : format binaire compressé, le plus flexible et généralement le meilleur choix car vous pouvez restaurer des tables individuelles
• Plain : script SQL en clair, lisible dans n'importe quel éditeur de texte
• Tar : archive non compressée, plus rare mais utile pour certains workflows de restauration

Après avoir sélectionné le format et le chemin de destination, pgAdmin lance pg_dump en arrière-plan et enregistre le fichier sur votre machine locale.

Créer une sauvegarde

Pour restaurer, allez dans Tools – Restore, sélectionnez votre fichier de sauvegarde et ciblez la base souhaitée.

Restaurer à partir d'une sauvegarde

Pour quoi faire ? Imaginez tester une migration destructrice sur votre base de dev. Faites une sauvegarde, exécutez la migration et, en cas de casse, restaurez pour revenir à un état maîtrisé.

Bonnes pratiques pour exécuter pgAdmin 4 dans Docker

Lancer pgAdmin 4 est une chose. Le faire tourner sans accroc dans la durée nécessite quelques réflexes supplémentaires. Voici des conseils concrets.

Gardez les identifiants hors de votre fichier Compose

Si votre docker-compose.yml finit sous contrôle de version – ce qui est fréquent – les mots de passe en dur suivront. Utilisez un fichier .env pour les identifiants et ajoutez-le au .gitignore. En production, allez plus loin avec les secrets Docker, qui montent les valeurs sensibles sous forme de fichiers plutôt que de variables d'environnement.

N'exposez jamais publiquement le port de pgAdmin

Par défaut, Docker lie les ports à 0.0.0.0, donc à toutes les interfaces – y compris publiques. Sur un serveur distant, cela rend votre instance pgAdmin accessible depuis Internet. Liez explicitement à 127.0.0.1 à la place :

ports:
  - "127.0.0.1:5050:5050"

Ainsi, pgAdmin n'est accessible que depuis le serveur lui-même. Utilisez un tunnel SSH ou un reverse proxy si vous avez besoin d'un accès à distance.

Figez vos tags d'image

Avec dpage/pgadmin4:latest, une nouvelle version sera tirée au prochain docker compose pull. Elle peut se comporter différemment, casser votre config ou introduire des changements inattendus. Préférez un tag spécifique comme dpage/pgadmin4:9.13 pour que toute l'équipe tourne sur la même version.

Précharger les connexions serveur avec servers.json

Si toute votre équipe partage la même configuration Compose, évitez à chacun d'enregistrer manuellement le serveur PostgreSQL. pgAdmin prend en charge un fichier servers.json qui pré-remplit les connexions au démarrage. Montez-le ainsi :

volumes:
  - ./servers.json:/pgadmin4/servers.json

Voici un servers.json minimal :

{
  "Servers": {
    "1": {
      "Name": "local-dev-postgres",
      "Group": "Servers",
      "Host": "postgres",
      "Port": 5432,
      "MaintenanceDB": "mydb",
      "Username": "admin",
      "SSLMode": "prefer"
    }
  }
}

Le serveur apparaîtra dès le démarrage de pgAdmin : aucune configuration manuelle n'est nécessaire.

Conclusion

Dans cet article, je vous ai guidé pas à pas pour configurer pgAdmin 4 dans Docker. Vous avez écrit un fichier Docker Compose pour lancer PostgreSQL et pgAdmin 4 ensemble, connecté les deux conteneurs via le DNS interne de Docker, et utilisé les fonctions clés de pgAdmin : Query Tool, explorateur de schéma et sauvegarde/restauration.

Le principe clé ici, c'est la reproductibilité.

Un fichier docker-compose.yml, un servers.json et un .env suffisent pour fournir à un collègue un environnement base de données entièrement configuré. De quoi éviter définitivement le fameux « ça marche chez moi ».

Pour aller plus loin sur Docker et la conteneurisation, découvrez notre cours Intermediate Docker. Il regorge d'astuces sur les builds multi-étapes, le réseau et un tour d'horizon approfondi de Compose.