Docker pgAdmin: Zo zet je een PostgreSQL-GUI op met Docker Compose

Steeds wisselen tussen sessies, syntax onthouden en hopen dat je geen typefout maakt in een destructieve query gaat snel vervelen. Er is geen visueel queryplan, geen schemabrowser en geen makkelijke manier om een database te back-uppen. Het werkt, maar ideaal is het niet.

pgAdmin 4 lost dat op met een browsergebaseerde GUI, speciaal gebouwd voor PostgreSQL. En het in Docker draaien betekent nul lokale installatie. Je hoeft alleen de container te starten.

In dit artikel laat ik je zien hoe je PostgreSQL en pgAdmin 4 met Docker Compose opzet, de twee containers met elkaar verbindt en de Query Tool, schemabrowser en back-upfuncties van pgAdmin gebruikt.

Om mee te doen heb je Docker geïnstalleerd en draaiend op je machine. Ben je nieuw met Docker Compose, lees dan onze gids om te zien hoe het multi-containerontwikkeling vereenvoudigt.

Wat is pgAdmin 4?

pgAdmin 4 is een open-source, browsergebaseerd beheer- en ontwikkelplatform voor PostgreSQL. Je gebruikt het via een webbrowser, dus er is geen desktopapp om te installeren. Het geeft je een GUI om databases te beheren, queries uit te voeren, schema's te inspecteren en back-ups te maken—zonder de command line aan te raken.

De officiële Docker-image is dpage/pgadmin4, onderhouden door het pgAdmin-ontwikkelingsteam.

pgAdmin 4 in Docker draaien heeft een paar echte voordelen ten opzichte van lokaal installeren. Ten eerste draagbaarheid: je hele databaseomgeving staat in één docker-compose.yml-bestand dat je met teamgenoten kunt delen. Ten tweede zijn er geen versieconflicten: pgAdmin draait in zijn eigen container, volledig geïsoleerd van de rest van je machine. En als je klaar bent, veegt docker compose down alles schoon.

pgAdmin 4 vs. andere PostgreSQL-GUI's

Er is geen gebrek aan GUI-tools voor databasemanagement. Zo verhoudt pgAdmin 4 zich tot twee populaire alternatieven.

pgAdmin 4 versus populaire alternatieven

DBeaver en TablePlus zijn goede tools, maar geen van beide heeft een officiële Docker-image. Draait je PostgreSQL-instantie al in Docker, dan is pgAdmin 4 een uitstekende match—je hoeft alleen één service toe te voegen aan je docker-compose.yml en alles draait samen in hetzelfde netwerk.

De omgeving opzetten met Docker Compose

De snelste manier om PostgreSQL en pgAdmin 4 samen te draaien is met één docker-compose.yml-bestand. Als je nieuw bent met het onderwerp, behandelt onze Docker Compose-gids de basis. Hier focus ik op de pgAdmin-specifieke configuratie.

Hier is het complete bestand dat je kunt kopiëren en plakken:

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:

Het veld depends_on vertelt Docker Compose dat de postgres-container moet starten vóór pgadmin. Zonder dit kan pgAdmin starten voordat PostgreSQL klaar is en de verbinding mislukt. Het wacht niet tot PostgreSQL volledig healthy is—alleen tot de container start. Dat is meestal genoeg om racecondities te voorkomen.

pgAdmin 4-omgevingsvariabelen

Twee omgevingsvariabelen zijn verplicht:

• PGADMIN_DEFAULT_EMAIL - het e-mailadres waarmee je inlogt op de pgAdmin-webinterface
• PGADMIN_DEFAULT_PASSWORD - het wachtwoord voor dat account

Een derde is optioneel, maar je kunt hem beter wel opgeven:

• PGADMIN_LISTEN_PORT - de poort waar pgAdmin binnen de container op luistert. Standaard is dat 80, maar 5050 instellen houdt het overzichtelijker bij het mappen van poorten.

Dat gezegd hebbende, credentials hardcoden in het Compose-bestand is geen goed idee, zeker niet als het bestand in versiebeheer belandt. Verplaats ze naar een .env-bestand.

Maak een .env-bestand in dezelfde map als je docker-compose.yml:

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

Verwijs daarna naar de variabelen in je Compose-bestand:

# 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 pikt .env-bestanden op wanneer je het commando draait, dus extra configuratie is niet nodig. Vergeet alleen niet .env toe te voegen aan je .gitignore, dan blijven je credentials uit de repo.

Volumes en datapersistentie

Het volume dat is gemount op /var/lib/pgadmin is waar pgAdmin data opslaat, zoals sessiegegevens, opgeslagen serververbindingen en configuratie. Dit uit het compose-bestand weglaten betekent dat je dat allemaal kwijtraakt elke keer dat de container herstart.

In het huidige compose-bestand heb je een named volume dat Docker op je host beheert. De data overleeft containerherstarts, -hercreaties en image-updates—zolang je het volume niet expliciet verwijdert met docker volume rm.

De stack starten en pgAdmin 4 openen

Met je docker-compose.yml klaar, start je de stack met één commando:

docker compose up -d

De -d-vlag draait beide containers in detached mode—ze starten op de achtergrond en je terminal blijft vrij. Controleer of beide containers draaien:

docker ps

Je zou zowel postgres als pgadmin moeten zien met de status Up.

Containerstatus

Als iets niet klopt, bekijk de pgAdmin-logs:

docker logs pgadmin

Een gezonde opstart ziet er zo uit:

pgAdmin-opstartlogs

Zie je hier een foutmelding, dan is het waarschijnlijk een van deze drie:

• Password authentication failed: je PGADMIN_DEFAULT_PASSWORD ontbreekt of is onjuist geformatteerd in het .env-bestand

• Port is already allocated: er draait al iets op poort 5050; wijzig de hostpoort in je Compose-bestand

• No such file or directory: het volumepad is onjuist of de container heeft geen schrijfrechten

Zodra beide containers draaien en de logs schoon zijn, open je je browser en ga je naar http://localhost:5050:

pgAdmin-inlogpagina

Log in met het e-mailadres en wachtwoord die je hebt ingesteld in PGADMIN_DEFAULT_EMAIL en PGADMIN_DEFAULT_PASSWORD. Je komt op het pgAdmin-dashboard, klaar om je PostgreSQL-server te registreren:

pgAdmin-startpagina

pgAdmin 4 verbinden met je PostgreSQL-container

Klik in de pgAdmin-zijbalk met de rechtermuisknop op Servers - Register - Server. Er opent een dialoog met twee tabbladen die je moet invullen: General en Connection.

Het tabblad General

Geef je server een duidelijke naam—iets als local-dev-postgres. Dit is alleen een label binnen pgAdmin, kies dus iets dat voor jouw setup logisch is.

Serverregistratie - tabblad General

Het tabblad Connection

Gebruik hier geen localhost. 

Binnen een Docker-netwerk verwijst localhost naar de container zelf—niet naar je hostmachine en niet naar de PostgreSQL-container. Docker heeft een eigen interne DNS en resolveert container-namen via de servicenamen die in je docker-compose.yml zijn gedefinieerd. Heet je PostgreSQL-service postgres, dan is dat de hostnaam die je gebruikt.

Vul de velden als volgt in:

• Host name/address: postgres (de servicenaam uit docker-compose.yml)

• Port: 5432

• Maintenance database: de waarde van POSTGRES_DB uit je Compose-bestand (bijv. mydb)

• Username: de waarde van POSTGRES_USER (bijv. admin)

• Password: de waarde van POSTGRES_PASSWORD

Klik op Save. 

Serverregistratie - tabblad Connection

Als alles klopt, verschijnt de server in de zijbalk en kun je hem uitklappen om je databases te bekijken:

Serverregistratie geslaagd

Dit betekent dat je verbonden bent.

De Query Tool gebruiken

Nu je verbonden bent, laat ik je de basis van pgAdmin 4 en Postgres in het algemeen zien.

Open de Query Tool via Tools - Query Tool in het topmenu. De interface heeft drie panelen:

• Editor: waar je SQL schrijft
• Data Output: waar resultaten verschijnen nadat je een query draait
• Messages: waar PostgreSQL statusberichten, fouten en uitvoeringsinfo stuurt

Querytool

SQL schrijven en uitvoeren

Laten we een eenvoudige tabel orders maken en wat data toevoegen. Je kunt elk blok draaien met de Play-knop of met F5, de sneltoets.

Draai dit om de tabel te maken:

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
);

Voeg een paar rijen in:

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

En nu gewoon de data opvragen:

SELECT * FROM orders;

Data opvragen

Resultaten verschijnen in het Data Output-paneel als een tabel. Je kunt kolommen sorteren, de breedte aanpassen en rijen direct uit het raster kopiëren.

Het visuele queryplan lezen

Om te zien wat er onder water gebeurt wanneer je een query draait, voer je EXPLAIN ANALYZE uit op je SELECT-statement:

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

Explain Analyze-resultaten

Het Data Output-paneel toont de ruwe output. Maar pgAdmin heeft een betere optie. Klik op de Explain-knop in de toolbar—pgAdmin rendert het queryplan dan als een interactieve grafiek.

Queryplan als grafiek

Nu is het simpel voor deze query, maar je krijgt er veel meer waarde uit wanneer je tabellen joint of complexere aggregaties uitvoert.

Dit is belangrijk omdat ruwe EXPLAIN-output lezen traag en foutgevoelig is. Het visuele plan maakt het meteen duidelijk wanneer PostgreSQL een full table scan doet op een grote tabel, of wanneer er een index is die niet wordt gebruikt.

Je databaseschema beheren

De zijbalk van pgAdmin geeft je een volledig overzicht van je databasestructuur—en laat je die via de GUI aanpassen.

De boomstructuur in de zijbalk is: Servers - jouw servernaam - Databases - jouw database - Schemas - public - Tables. Klap een tabel uit en je ziet Columns, Indexes en Constraints als childnodes. Klik op een van deze om de details in het rechterpaneel te bekijken.

Tabellen maken en wijzigen

Om een nieuwe tabel te maken, klik je met rechts op Tables onder je schema en kies je Create - Table. Er opent een dialoog met een paar tabbladen.

Tabellen maken

Op het tabblad General stel je de tabelnaam in. Ga naar het tabblad Columns om je kolommen toe te voegen—elke rij laat je de kolomnaam, het datatype, de lengte en of hij nullable is instellen. Het tabblad Constraints verzorgt primary keys, foreign keys en unique constraints.

Om een index toe te voegen aan een bestaande tabel, klap je de tabel in de zijbalk uit, klik je met rechts op Indexes en kies je Create - Index. Kies de te indexeren kolommen en selecteer het indextype—btree is de standaard en werkt in de meeste gevallen.

Een index maken

Back-up en herstel

Om een database te back-uppen, ga je naar Tools - Backup. Je moet een formaat kiezen:

• Custom: gecomprimeerd, binair formaat; de meest flexibele optie en meestal de beste keuze, omdat je er afzonderlijke tabellen uit kunt herstellen
• Plain: een gewone SQL-script die je in elke teksteditor kunt openen en lezen
• Tar: een ongecomprimeerd archief; minder gebruikelijk maar nuttig voor sommige herstelworkflows

Na het kiezen van een formaat en een doelpad draait pgAdmin op de achtergrond pg_dump en slaat het bestand op je lokale machine op.

Een back-up maken

Om te herstellen, ga je naar Tools - Restore, selecteer je je back-upbestand en wijs je het aan de doeldatabase toe.

Herstellen vanuit een back-up

Als je je afvraagt waarom dit handig is: stel dat je een destructieve migratie test op je dev-database. Maak eerst een back-up, voer de migratie uit en als er iets breekt, herstel je de back-up om terug te gaan naar een bekende staat.

Best practices voor pgAdmin 4 in Docker

pgAdmin 4 aan de praat krijgen is één ding. Het soepel laten draaien vraagt om nog wat extra kennis. Hier zijn een paar praktische tips.

Houd credentials uit je Compose-bestand

Als je docker-compose.yml in versiebeheer belandt—en dat gebeurt meestal—gaan hardgecodeerde wachtwoorden mee. Gebruik een .env-bestand voor credentials en voeg het toe aan .gitignore. Ga voor productieomgevingen een stap verder en gebruik Docker secrets, waarmee gevoelige waarden als bestanden worden gemount in plaats van als omgevingsvariabelen.

Stel de pgAdmin-poort nooit publiek bloot

Standaard bindt Docker poorten aan 0.0.0.0, wat elke netwerkinterface betekent—ook publieke. Op een externe server maakt dat je pgAdmin-instantie bereikbaar vanaf het internet. Bind expliciet aan 127.0.0.1 in plaats daarvan:

ports:
  - "127.0.0.1:5050:5050"

Hierdoor is pgAdmin alleen vanaf de server zelf toegankelijk. Gebruik een SSH-tunnel of een reverse proxy als je externe toegang nodig hebt.

Pin je imagetags

Met dpage/pgadmin4:latest trek je een nieuwe versie binnen de volgende keer dat iemand docker compose pull draait. Die nieuwe versie kan zich anders gedragen, je configuratie breken of onverwachte wijzigingen introduceren. Gebruik een specifieke tag zoals dpage/pgadmin4:9.13 zodat ieder teamlid exact dezelfde versie draait.

Serververbindingen vooraf laden met servers.json

Als je hele team dezelfde Compose-setup deelt, laat dan niet iedereen de PostgreSQL-server registreren na het opstarten van de stack. pgAdmin ondersteunt een servers.json-bestand dat verbindingen bij het starten vooraf invult. Mount het in de container zoals dit:

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

Zo ziet een minimaal servers.json-bestand eruit:

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

De server verschijnt bij het starten van pgAdmin—geen handmatige setup nodig.

Conclusie

In dit artikel heb ik je van nul af aan laten zien hoe je pgAdmin 4 in Docker opzet. Je hebt een Docker Compose-bestand geschreven dat PostgreSQL en pgAdmin 4 samen opstart, de twee containers verbonden met Docker's interne DNS en de kernfuncties van pgAdmin gebruikt—de Query Tool, schemabrowser en back-up/herstelworkflow.

Het kernprincipe hier is reproduceerbaarheid. 

Een docker-compose.yml-bestand, een servers.json en een .env-bestand zijn alles wat je nodig hebt om een teamgenoot een volledig geconfigureerde databaseomgeving te geven. Zo voorkom je voorgoed het “op mijn machine werkt het”-probleem.

Wil je dieper in Docker en containerization duiken, bekijk dan onze Intermediate Docker-cursus. Die zit vol handige tips over multi-stage builds, netwerken en een deep dive in Compose.