PostgreSQL in Docker: een stapsgewijze gids voor beginners

PostgreSQL instellen in Docker

Het enige wat je nodig hebt om de Postgres-database in Docker te draaien is de Docker-engine zelf.

In deze sectie neem ik je mee door de vereisten en het draaien van een volledig functionele PostgreSQL-database in een Docker-container.

Vereisten

Voordat je met PostgreSQL in Docker begint, moet Docker op je systeem geïnstalleerd zijn.

De installatie verschilt per besturingssysteem. Windows- en macOS-gebruikers kunnen simpelweg Docker Desktop installeren, een gebruiksvriendelijke grafische interface om containers te beheren. Download het via de officiële Docker-website.

Linux-gebruikers kunnen Docker Engine direct installeren via de package manager van hun distributie. Bijvoorbeeld op Ubuntu:

sudo apt update
sudo apt install docker.io
sudo systemctl enable --now docker

Naast Docker is het aan te raden dat je basiskennis hebt van terminalcommando’s en van Docker-concepten zoals images, containers en volumes. Deze praktische gidsen van DataCamp helpen je op weg:

• Docker voor beginners: een praktische gids voor containers
• Docker installeren op Ubuntu: van setup tot je eerste container

De PostgreSQL Docker-image pullen

Voordat je PostgreSQL draait, download je de officiële PostgreSQL Docker-image van Docker Hub. Deze image dient als template voor het aanmaken van containers.

Om de nieuwste PostgreSQL-image te pullen, open je je terminal of opdrachtprompt en voer je uit:

docker pull postgres

Dit commando downloadt de laatste stabiele versie van PostgreSQL. Als je een specifieke versie nodig hebt, kun je een tag opgeven:

docker pull postgres:17

Afbeelding 1 - De nieuwste stabiele versie van de PostgreSQL-database-image pullen

Enkele veelgebruikte PostgreSQL-imagetags zijn:

• postgres:latest - De meest recente stabiele PostgreSQL-versie
• postgres:17 - PostgreSQL-versie 14.x (de meest recente patch van versie 17)
• postgres:17.4 - Een specifieke versie (in dit geval 17.4).
• postgres:bookworm - PostgreSQL gebouwd op de Debian Bookworm Linux-distributie.

Je kunt alle beschikbare tags bekijken op de officiële PostgreSQL Docker Hub-pagina.

PostgreSQL draaien in een Docker-container

Zodra je de PostgreSQL-image hebt, kun je met één commando een container aanmaken en starten:

docker run --name postgres-db -e POSTGRES_PASSWORD=mypassword postgres

Afbeelding 2 - Een PostgreSQL-container starten

Dit commando maakt een nieuwe container met de naam postgres-db en zet een omgevingsvariabele voor het PostgreSQL-wachtwoord.

Dit basiscommando heeft echter beperkingen. Ik raad aan om extra opties te gebruiken:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mypassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -p 5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Afbeelding 3 - Een PostgreSQL-container starten met env-variabelen in detached-modus

Ik licht deze extra opties even toe:

• Omgevingsvariabelen:
  • POSTGRES_PASSWORD: Stelt het wachtwoord in voor de PostgreSQL-superuser (vereist).
  • POSTGRES_USER: Maakt een nieuwe superuser met deze naam (standaard “postgres” als niet opgegeven).
  • POSTGRES_DB: Maakt een nieuwe database met deze naam (standaard de gebruikersnaam als niet opgegeven).
• Poortmapping (-p 5432:5432) koppelt de PostgreSQL-poort (5432) van de container aan dezelfde poort op je host, zodat je met localhost:5432 kunt verbinden.
• Volumekoppeling (-v postgres-data:/var/lib/postgresql/data) maakt een Docker-volume met de naam postgres-data dat de databasebestanden buiten de container opslaat. Zo raak je je data niet kwijt als de container stopt of wordt verwijderd.
• De -d-vlag zorgt dat de container in detached-modus draait. Simpel gezegd: op de achtergrond.

Je kunt controleren of de container draait met:

docker ps

Afbeelding 4 - Alle draaiende containers weergeven

In de volgende sectie laat ik zien hoe je je PostgreSQL-container verder kunt configureren voor specifieke use-cases.

PostgreSQL configureren in Docker

De basissetup uit de vorige sectie helpt je op weg, maar voor alles wat geavanceerder is, wil je je PostgreSQL-container waarschijnlijk aanpassen.

Daar gaat deze sectie over.

Persistente opslag met volumes instellen

Een van de belangrijkste aspecten van een database in Docker draaien is ervoor zorgen dat je data behouden blijft buiten de levenscyclus van de container. Standaard gaat alle data in een container verloren zodra je de container verwijdert. Voor een database is dat zelden wat je wilt.

Docker-volumes bieden hiervoor een oplossing door data buiten het container-bestandssysteem op te slaan.

Om dit in te stellen, begin je met het aanmaken van een named volume:

docker volume create postgres-data

Je kunt optioneel de details van het volume bekijken met:

docker volume inspect postgres-data

Afbeelding 5 - Volumedetails weergeven

Koppel bij het starten van je PostgreSQL-container het volume aan de PostgreSQL-datadirectory:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

De parameter -v postgres-data:/var/lib/postgresql/data verbindt het named volume met de datadirectory van de container.

Samengevat, volumes gebruiken voor PostgreSQL biedt deze voordelen:

• Je data blijft behouden, zelfs als je de container verwijdert.
• Je kunt de container stoppen, starten of upgraden zonder dataverlies.
• Je kunt back-ups maken door het volume te back-uppen.
• Betere performance vergeleken met bind mounts (vooral op macOS en Windows).

Poorten exposen om verbinding te maken met PostgreSQL

Om verbinding te maken met je PostgreSQL-database vanuit applicaties op je host, moet je poort 5432 (PostgreSQL) exposen naar je lokale systeem.

De simpelste aanpak is om poort 5432 van de container te mappen naar dezelfde poort op je host:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d postgres

De parameter -p 5432:5432 koppelt poort 5432 van de container aan poort 5432 op je host.

Als PostgreSQL of een andere service al poort 5432 gebruikt op je host, kun je naar een andere poort mappen:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5433:5432 \
  -d postgres

Nu is poort 5432 in de container gemapt naar poort 5433 op je host. Bij het verbinden geef je dus poort 5433 op in plaats van de standaard 5432.

Standaard wordt de poort op alle netwerkinterfaces (0.0.0.0) geëxposed. Je kunt dit optioneel beperken tot localhost voor extra security:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -d postgres

Hiermee zijn verbindingen alleen toegestaan vanaf je lokale machine, niet vanaf andere machines op het netwerk.

PostgreSQL-instellingen configureren

Veel standaard PostgreSQL-instellingen kun je aanpassen bij het starten van je container. Een veelgebruikte aanpak, maar niet de enige, is het gebruik van omgevingsvariabelen.

Hier zijn een paar variabelen die je kunt gebruiken om de database te configureren:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -e POSTGRES_INITDB_ARGS="--data-checksums" \
  -e POSTGRES_HOST_AUTH_METHOD=scram-sha-256 \
  -d postgres

En dit is wat elk van deze doet:

• POSTGRES_PASSWORD: Stelt het superuser-wachtwoord in (vereist).
• POSTGRES_USER: Stelt de superusername in (standaard “postgres”).
• POSTGRES_DB: Stelt de standaarddatabasenaam in (standaard gelijk aan de username).
• POSTGRES_INITDB_ARGS: Geeft argumenten door aan PostgreSQL’s initdb-commando.
• POSTGRES_HOST_AUTH_METHOD: Stelt de authenticatiemethode in.

Naast omgevingsvariabelen kun je ook de PostgreSQL-configuratie aanpassen om geavanceerdere wijzigingen in te stellen.

Veelvoorkomende PostgreSQL-instellingen om aan te passen zijn:

• max_connections: Bepaalt hoeveel connecties PostgreSQL accepteert (standaard 100).
• shared_buffers: Stelt geheugen in voor caching (standaard vaak te laag voor productie).
• work_mem: Geheugen voor querybewerkingen.
• maintenance_work_mem: Geheugen voor onderhoudstaken.

Voor een praktische uitwerking: maak eerst een bestand aan, noem het bijvoorbeeld my-postgres-conf:

max_connections = 200
shared_buffers = 1GB
work_mem = 16MB
maintenance_work_mem = 256MB

Koppel dit bestand nu bij het starten van de container:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./my-postgres.conf:/etc/postgresql/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres \
  -c 'config_file=/etc/postgresql/postgresql.conf'

Kortom, door persistentie, netwerktoegang en PostgreSQL-instellingen goed te configureren, creëer je een Docker-gebaseerde PostgreSQL-omgeving die precies doet wat jij wilt. De basisimage postgres:latest is precies dat — de basis — er valt veel te tweaken.

In de volgende sectie laat ik zien hoe je verbinding maakt met de in Docker draaiende PostgreSQL-database.

Verbinden met PostgreSQL die in Docker draait

Nu je PostgreSQL-container draait, is de volgende stap verbinden. Anders heeft een database draaien weinig zin.

In deze sectie laat ik je twee manieren zien om te verbinden met je gecontaineriseerde PostgreSQL-database: via de psql-commandline en via een grafische interface.

Ter referentie: ik draai mijn databasecontainer met dit commando:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres

Verbinden met de psql-commandline tool

De psql-commandline tool is de officiële PostgreSQL-client waarmee je via SQL-commando’s met de database werkt. 

Om vanaf je host verbinding te maken met de PostgreSQL-database in de container, voer je dit commando uit (pas user en database aan):

docker exec -it postgres-db psql -U myuser -d mydatabase

Afbeelding 6 - Verbinden met de Postgres-database via psql

En dat is het!

Als je niet zeker weet wat het commando doet, hier een korte uitleg:

• docker exec -it postgres-db: Voer een interactieve opdracht uit in de container met de naam “postgres-db”.
• psql -U myuser -d mydatabase: Start psql en verbind als “myuser” met de database “mydatabase”.

Als verbinden niet lukt, check dan deze veelvoorkomende issues:

• Bevestig dat de container draait met docker ps.
• Controleer de poortmapping met docker port postgres-db.

Verbinden met een GUI-tool

Veel developers werken liever met een grafische tool dan met de CLI — ik ook. pgAdmin is een populaire en gratis keuze voor PostgreSQL, maar verbinden werkt vergelijkbaar in tools als DBeaver, DataGrip of TablePlus.

De installatie van pgAdmin is rechttoe rechtaan, dus die sla ik hier over.

Ga ervan uit dat het geïnstalleerd en gestart is. Klik dan met rechts op “Servers” in het browserpaneel en kies “Register > Server”. Geef in het tabblad General je verbinding een naam:

Afbeelding 7 - pgAdmin-tabblad General

Ga daarna naar het tabblad “Connection” en vul deze gegevens in:

• Host name/address: localhost
• Port: 5432 (of de poort waarnaar je hebt gemapt)
• Maintenance database: mydatabase
• Username: myuser
• Password: Je PostgreSQL-wachtwoord

Afbeelding 8 - pgAdmin-tabblad Connection

Klik tenslotte op “Save” om te verbinden:

Afbeelding 9 - Succesvolle verbinding

Zodra je verbonden bent, kun je met je database werken zoals met een lokaal geïnstalleerde of cloud-geprovisioneerde PostgreSQL-instantie. Het mooie van Docker: vanuit je app of client is er geen verschil — het is gewoon een PostgreSQL-database op het opgegeven adres.

>Programmatic toegang tot je PostgreSQL-database nodig? Leer hoe je er vanuit Python mee verbindt.

In de volgende sectie laat ik zien hoe je je PostgreSQL-container beheert, inclusief stoppen, starten en monitoren.

PostgreSQL beheren in Docker

Een PostgreSQL-database in een container draaien en ermee verbinden is één ding, maar beheer is weer wat anders. Gelukkig heb je een handvol commando’s tot je beschikking.

In deze sectie behandel ik essentiële acties zoals je container stoppen en starten, logs bekijken en je PostgreSQL-versie up-to-date houden.

De PostgreSQL-container stoppen, herstarten en verwijderen

Met Docker’s commandline-tools beheer je de lifecycle van je PostgreSQL-container.

Om een draaiende PostgreSQL-container te stoppen, voer je uit:

docker stop postgres-db

Start hem daarna weer met:

docker start postgres-db

Afbeelding 10 - De container stoppen en starten

Wil je een draaiende container herstarten — handig na bepaalde configuratiewijzigingen — voer dan uit:

docker restart postgres-db

In gevallen waarin je helemaal klaar bent met een container en deze wilt verwijderen, gebruik je deze twee commando’s:

docker stop postgres-db
docker rm postgres-db

Houd er rekening mee dat het verwijderen van een container je data niet wist als je een volume correct hebt ingesteld. Je data staat nog steeds in het eerder gemaakte volume postgres-data.

Controleer of de container is verwijderd met:

docker ps -a

De vlag -a toont alle containers, inclusief gestopte. Als je container succesvol is verwijderd, staat hij niet meer in deze lijst:

Afbeelding 11 - Alle containers weergeven

Logs inspecteren

Als er iets misgaat of je je database-activiteit wilt monitoren, is de logs checken een goede eerste stap.

Voer dit commando uit om de logs van je PostgreSQL-container te bekijken:

docker logs postgres-db

Dit toont alle logs sinds de container is gestart. Bij veel logs kun je de output beperken, bijvoorbeeld tot de laatste 50 regels:

docker logs --tail 50 postgres-db

Afbeelding 12 - Containerlogs bekijken

Wil je de logs realtime volgen, voer dan dit commando uit:

docker logs -f postgres-db

Afbeelding 13 - Realtime containerlogs bekijken

Dit is vooral handig bij het debuggen van verbindingsproblemen of het volgen van databaseactiviteit tijdens development.

Druk op Ctrl+C/CMD+C om het volgen te stoppen.

PostgreSQL bijwerken in Docker

Na verloop van tijd wil je je PostgreSQL-versie bijwerken voor de nieuwste features, performanceverbeteringen en beveiligingspatches.

Op het moment van schrijven is postgres:17.4 de nieuwste versie, maar stel dat postgres:17.5 net is uitgebracht. In deze sectie laat ik zien hoe je de databaseversie in je container bijwerkt.

Begin met het pullen van de nieuwste PostgreSQL-image (of een specifieke versie):

docker pull postgres:17.5

Stop en verwijder vervolgens de bestaande container:

docker stop postgres-db
docker rm postgres-db

Maak ten slotte een nieuwe container met hetzelfde volume:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -e POSTGRES_USER=myuser \
  -e POSTGRES_DB=mydatabase \
  -v postgres-data:/var/lib/postgresql/data \
  -p 5432:5432 \
  -d postgres:17.5

Omdat je hetzelfde volume (postgres-data) gebruikt, blijven al je bestaande gegevens behouden.

Als je een major-versie upgrade (zoals 17 naar 18), voert PostgreSQL bij het starten automatisch de benodigde datamigraties uit. Houd dan wel rekening met het volgende:

• Test major upgrades eerst in een niet-productieomgeving.
• Maak altijd een back-up van je datavolume voordat je een major upgrade uitvoert.
• Check de PostgreSQL-releasenotes op breaking changes.

Om voor het upgraden een back-up te maken, voer je dit commando uit:

docker run --rm -v postgres-data:/data -v $(pwd):/backup postgres:17.4 \
  bash -c "pg_dumpall -U myuser > /backup/postgres_backup.sql"

Dit maakt een SQL-back-upbestand in je huidige map, waarmee je je data kunt herstellen als er iets misgaat.

>Onze PostgreSQL Basics Cheat Sheet kun je handig als snel naslagwerk gebruiken tijdens het werken in Docker.

In de volgende sectie behandel ik best practices voor PostgreSQL in Docker, inclusief security-overwegingen en optimalisatietips.

Best practices voor PostgreSQL in Docker

De flexibiliteit van Docker vraagt om verantwoordelijkheid. In deze sectie deel ik best practices zodat je gecontaineriseerde PostgreSQL-setup betrouwbaar, veilig en volgens de standaarden is.

Houd je data veilig met regelmatige back-ups

Ongeacht hoe je PostgreSQL draait, back-ups zijn onmisbaar. Ik noemde back-ups al eerder, maar hier gaan we een stap verder. 

De simpelste manier om een PostgreSQL-database in Docker te back-uppen is met pg_dump:

docker exec -t postgres-db pg_dump -U myuser mydatabase > backup.sql

Afbeelding 14 - PostgreSQL-back-up

Voor een volledige back-up van alle databases, inclusief rollen en tablespaces, gebruik je pg_dumpall:

docker exec -t postgres-db pg_dumpall -U myuser > full_backup.sql

Afbeelding 15 - Volledige PostgreSQL-databaseback-up

Deze afbeelding toont slechts een paar back-upcommando’s; alles op één scherm passen lukt niet.

Om je back-ups te automatiseren kun je een eenvoudige shellscript maken en die via cron draaien:

#!/bin/bash
# backup.sh
TIMESTAMP=$(date +"%Y%m%d")
BACKUP_DIR="/Users/dradecic/Documents/pg-backups"

# Zorg dat de back-upmap bestaat
mkdir -p $BACKUP_DIR

# Maak de back-up
docker exec postgres-db pg_dumpall -U myuser | gzip > $BACKUP_DIR/postgres_$TIMESTAMP.sql.gz

# Verwijder back-ups ouder dan 30 dagen
find $BACKUP_DIR -name "postgres_*.sql.gz" -mtime +30 -delete

Maak het script uitvoerbaar en voer het uit:

chmod +x backup.sh

bash backup.sh

Afbeelding 16 - Een PostgreSQL-databaseback-upscript uitvoeren

Om de back-up helemaal te automatiseren, kun je het script aan je crontab toevoegen om het dagelijks te draaien:

0 3 * * * /path/to/backup.sh

Dit schema draait de back-up elke dag om 03.00 uur, maar pas de tijd en frequentie gerust aan.

>Bekijk mijn uitgebreide gids over cron-jobs om meer te leren over dit handige automatiseringstool.

Overweeg in productieomgevingen om back-ups off-site of in cloudopslag te bewaren voor disaster recovery.

Gebruik named volumes voor datapersistentie

Hoewel ik volumes eerder kort behandelde, is het de moeite waard om ze uitgebreider te bekijken.

Als vuistregel moet je PostgreSQL nooit in Docker draaien zonder een goed geconfigureerd volume. Doe je dat wel, dan ben je je data kwijt als de container wordt verwijderd of als Docker opruimacties uitvoert.

Named volumes (in plaats van anonieme volumes) maken back-uppen en beheer een stuk makkelijker:

# Maak een named volume aande
docker volume create postgres-data

# Gebruik het bij het starten van de container
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Niets nieuws hier.

Named volumes zijn ook makkelijker te back-uppen. Om een back-up te maken van het hele volume, voer je uit:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data-backup.tar.gz /data

Dit maakt een bestand postgres-data-backup.tar.gz in dezelfde map van waaruit je het commando hebt uitgevoerd.

Om dit volume te herstellen, voer je het volgende uit:

docker run --rm -v postgres-data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/postgres-data-backup.tar.gz --strip 1"

Dat was het!

PostgreSQL beveiligen in Docker

Beveiliging mag bij databases nooit een bijzaak zijn. In deze subsectie neem ik enkele essentiële praktijken door om je PostgreSQL-container te beveiligen.

Gebruik sterke en unieke wachtwoorden

Vermijd standaard- of zwakke wachtwoorden. Genereer een sterk, willekeurig wachtwoord voor je PostgreSQL-superuser:

export POSTGRES_PASSWORD=$(openssl rand -base64 32)
echo "$POSTGRES_PASSWORD" > postgres-password.txt

docker run --name postgres-db \
  -e POSTGRES_PASSWORD="$POSTGRES_PASSWORD" \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Afbeelding 17 - Een veilig wachtwoord gebruiken

Sla dit wachtwoord veilig op, bijvoorbeeld in een wachtwoordmanager of een omgevingsvariabelenbestand dat niet in versiebeheer staat.

Beperk netwerktoegang

Standaard exposeert Docker de PostgreSQL-poort op alle interfaces. Voor betere beveiliging, zeker in productie, beperk je toegang tot localhost:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 127.0.0.1:5432:5432 \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Gebruik een aangepaste PostgreSQL-configuratie

Maak een veiligere PostgreSQL-configuratie door parameters zoals hieronder te wijzigen:

# SSL vereisen
ssl = on
ssl_cert_file = '/etc/ssl/certs/ssl-cert-snakeoil.pem'
ssl_key_file = '/etc/ssl/private/ssl-cert-snakeoil.key'

# Aantal verbindingspogingen beperken
max_connections = 100
authentication_timeout = 1min

# Toegang beperken
listen_addresses = 'localhost'

Mount dit configuratiebestand bij het starten van je container:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v ./pg_hba.conf:/var/lib/postgresql/data/pg_hba.conf \
  -v ./postgresql.conf:/var/lib/postgresql/data/postgresql.conf \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

Update je PostgreSQL-image regelmatig

Houd je PostgreSQL-versie up-to-date voor de nieuwste beveiligingspatches:

docker pull postgres:latest
docker stop postgres-db
docker rm postgres-db
# Maak daarna opnieuw aan met de nieuwste image

Met deze best practices bouw je een betrouwbaardere en veiligere PostgreSQL-omgeving in Docker die geschikt is voor zowel development als productie.

In de volgende sectie behandel ik het oplossen van veelvoorkomende problemen met PostgreSQL in Docker.

PostgreSQL in Docker troubleshooten

Vroeg of laat loop je tegen issues aan bij het draaien van PostgreSQL in Docker. In deze sectie behandel ik veelvoorkomende problemen en hun oplossingen, zodat je tijd en frustratie bespaart.

Veelvoorkomende issues met PostgreSQL-containers

Een veelvoorkomend probleem is dat de container direct stopt na het starten. Check in dat geval de logs om de oorzaak te vinden:

docker logs postgres-db

De fout kan te maken hebben met rechtenproblemen bij gemounte volumes. Dan zie je mogelijk een vergelijkbaar logbericht:

initdb: could not change permissions of directory "/var/lib/postgresql/data": Operation not permitted

Los dit op door eigendom en permissies van je volume te controleren en zo nodig te herstellen:

# Check het eigenaarschap
docker run --rm -v postgres-data:/data alpine ls -la /data

# Herstel de permissies
docker run --rm -v postgres-data:/data alpine chmod 700 /data

Een ander veelvoorkomend probleem is het ontbreken van vereiste omgevingsvariabelen. Een typisch logbericht ziet er dan zo uit:

Database is uninitialized and superuser password is not specified

Zorg ervoor dat je de vereiste omgevingsvariabele POSTGRES_PASSWORD zet — of welke variabele dan ook nodig is:

docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data:/var/lib/postgresql/data \
  -d postgres

De fout “Data directory not empty but missing PostgreSQL files” komt ook vaak voor. Je ziet dan waarschijnlijk dit logbericht:

PostgreSQL Database directory appears to contain a database; Skipping initialization

Gevolgd door fouten over ontbrekende bestanden.

Dit gebeurt meestal als je een volume hebt gemount dat wel bestanden bevat maar geen geldige PostgreSQL-database. Re-initialiseer dan met een nieuw volume:

docker volume create postgres-data-new
docker run --name postgres-db \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -v postgres-data-new:/var/lib/postgresql/data \
  -d postgres

Verbindingsproblemen oplossen

Kun je niet verbinden met je PostgreSQL-database in een container, begin dan met controleren of de container draait:

docker ps | grep postgres-db

Als hij niet in de lijst staat, is hij mogelijk gecrasht. Check dan de logs zoals eerder beschreven.

Staat hij er wel maar lukt verbinden nog steeds niet, controleer dan de poortmapping:

docker port postgres-db

Je zou iets als dit moeten zien:

Afbeelding 18 - Poortmapping van de container

Zo niet, dan is je mapping niet correct. Maak de container opnieuw aan met de juiste -p-optie.

Lukt verbinden nog steeds niet, controleer dan je verbindingsinstellingen. Check deze parameters:

• Hostname: localhost of 127.0.0.1 (niet de containernaam).
• Port: De hostpoort uit je mapping (meestal 5432).
• Username: De waarde van POSTGRES_USER (standaard “postgres”).
• Password: De waarde van POSTGRES_PASSWORD.
• Database: De waarde van POSTGRES_DB (standaard gelijk aan POSTGRES_USER).

Probeer het opnieuw nadat je dit hebt gecorrigeerd. Blijft het probleem bestaan, test dan de verbinding binnen de container:

docker exec -it postgres-db psql -U postgres

Als dit wel werkt, zit het probleem in je poortmapping of extern netwerk.

Controleer tot slot op firewall-issues. De firewall van je systeem kan verbindingen naar de PostgreSQL-poort blokkeren, dus check dat even:

# Linux
sudo iptables -L | grep 5432

# macOS
sudo pfctl -sr | grep 5432

Door deze veelvoorkomende issues te controleren, kun je de meeste problemen met PostgreSQL in Docker identificeren en oplossen. Kom je er nog steeds niet uit, dan zijn de documentatie en communityfora van PostgreSQL en Docker uitstekende bronnen voor specifieker troubleshoot-advies.

Samenvatting: PostgreSQL-database in Docker

En daar is-ie — de ultieme gids voor het configureren en draaien van PostgreSQL-databases in Docker! Ik heb alles behandeld om te starten, van je eerste container opzetten tot configureren, verbinden en beheren. 

Traditionele PostgreSQL-opties, zoals lokaal installeren of in de cloud provisionen, zijn voor development-doeleinden vaak suboptimaal of duur. Docker overbrugt die kloof. Of je het nu gebruikt voor lokale ontwikkeling, testen of zelfs productie: gecontaineriseerde PostgreSQL biedt flexibiliteit en consistentie die moeilijk te evenaren zijn.

Je bent nu meer dan klaar om een Dockerized Postgres-database in je applicaties te integreren.

Wil je dieper de materie in, dan raad ik deze cursussen van DataCamp aan:

• Creating PostgreSQL Databases
• Introduction to Docker
• SQL for Database Administrators
• Functions for Manipulating Data in PostgreSQL