Docker pgAdmin: So richtest du eine PostgreSQL-GUI mit Docker Compose ein

Zwischen Sessions zu wechseln, Syntax auswendig zu können und zu hoffen, dass dir kein Tippfehler bei einer destruktiven Query passiert, wird schnell mühsam. Es gibt keinen visuellen Query-Plan, keinen Schema-Browser und keine einfache Möglichkeit, eine Datenbank zu sichern. Es funktioniert, ist aber weit weg von ideal.

pgAdmin 4 löst das mit einer browserbasierten GUI speziell für PostgreSQL. Und in Docker ausgeführt heißt das: keine lokale Installation. Du startest einfach den Container.

In diesem Artikel zeige ich dir, wie du PostgreSQL und pgAdmin 4 mit Docker Compose aufsetzt, beide Container verbindest und das Query Tool, den Schema-Browser und die Backup-Funktionen von pgAdmin nutzt.

Zum Mitmachen brauchst du Docker installiert und laufend auf deinem Rechner. Wenn du neu bei Docker Compose bist, lies unseren Guide, um zu sehen, wie es die Arbeit mit mehreren Containern vereinfacht.

Was ist pgAdmin 4?

pgAdmin 4 ist eine Open-Source-, browserbasierte Admin- und Entwicklungsplattform für PostgreSQL. Du greifst über den Browser zu, installierst also keine Desktop-App. Du bekommst eine GUI, um Datenbanken zu verwalten, Queries auszuführen, Schemata zu prüfen und Backups zu erstellen – ganz ohne Kommandozeile.

Das offizielle Docker-Image ist dpage/pgadmin4 und wird vom pgAdmin-Entwicklungsteam gepflegt.

pgAdmin 4 in Docker auszuführen hat echte Vorteile gegenüber einer lokalen Installation. Erstens Portabilität – deine gesamte Datenbankumgebung steckt in einer docker-compose.yml, die du mit dem Team teilen kannst. Zweitens gibt es keine Versionskonflikte – pgAdmin läuft in seinem eigenen Container, komplett isoliert vom Rest deines Systems. Und wenn du fertig bist, räumt docker compose down sauber auf.

pgAdmin 4 vs. andere PostgreSQL-GUIs

Es mangelt nicht an GUI-Tools für Datenbanken. So schneidet pgAdmin 4 im Vergleich zu zwei beliebten Alternativen ab.

pgAdmin 4 im Vergleich zu beliebten Alternativen

DBeaver und TablePlus sind gute Tools, aber keines hat ein offizielles Docker-Image. Wenn deine PostgreSQL-Instanz bereits in Docker läuft, ist pgAdmin 4 die ideale Ergänzung – du fügst in deiner docker-compose.yml nur einen Service hinzu, und alles läuft im selben Netzwerk.

Umgebung mit Docker Compose einrichten

Am schnellsten bringst du PostgreSQL und pgAdmin 4 gemeinsam mit einer einzigen docker-compose.yml ans Laufen. Wenn du erst einsteigst, deckt unser Docker-Compose-Guide die Grundlagen ab. Hier konzentriere ich mich auf die pgAdmin-spezifische Konfiguration.

Hier ist die komplette Datei zum Kopieren und Einfügen:

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:

Das Feld depends_on weist Docker Compose an, den postgres-Container vor pgadmin zu starten. Ohne diese Angabe könnte pgAdmin vor PostgreSQL starten und die Verbindung fehlschlagen. Es wartet zwar nicht, bis PostgreSQL vollständig „healthy“ ist – nur bis der Container läuft. Das reicht aber, um die meisten Race Conditions zu vermeiden.

pgAdmin-4-Umgebungsvariablen

Zwei Umgebungsvariablen sind verpflichtend:

• PGADMIN_DEFAULT_EMAIL – die E-Mail-Adresse, mit der du dich im pgAdmin-Webinterface anmeldest
• PGADMIN_DEFAULT_PASSWORD – das Passwort für dieses Konto

Eine dritte ist optional, sollte aber gesetzt werden:

• PGADMIN_LISTEN_PORT – der Port, auf dem pgAdmin im Container lauscht. Standard ist 80, aber 5050 hält das Port-Mapping übersichtlicher.

Allerdings ist es keine gute Idee, Zugangsdaten hartkodiert in der Compose-Datei zu speichern – erst recht nicht, wenn sie in die Versionsverwaltung wandert. Verschiebe sie stattdessen in eine .env-Datei.

Erstelle eine .env-Datei im selben Verzeichnis wie deine docker-compose.yml:

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

Und referenziere die Variablen in deiner Compose-Datei:

# 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 liest .env-Dateien automatisch beim Start ein, es ist also keine zusätzliche Konfiguration nötig. Denk nur daran, .env in deine .gitignore aufzunehmen – so bleiben die Zugangsdaten aus dem Repo.

Volumes und Datenpersistenz

Das Volume auf /var/lib/pgadmin ist der Speicherort für die pgAdmin-Daten wie Sessions, gespeicherte Serververbindungen und Konfiguration. Wenn du das aus der Compose-Datei entfernst, verlierst du all das bei jedem Container-Neustart.

In der aktuellen Compose-Datei nutzt du ein benanntes Volume, das Docker auf deinem Host verwaltet. Die Daten überstehen Container-Neustarts, Neu-Erstellungen und Image-Updates – solange du das Volume nicht explizit mit docker volume rm löschst.

Stack starten und auf pgAdmin 4 zugreifen

Mit deiner fertigen docker-compose.yml startest du den Stack mit einem Befehl:

docker compose up -d

Das Flag -d startet beide Container im Detached Mode – sie laufen im Hintergrund und dein Terminal bleibt frei. So prüfst du, ob beide Container laufen:

docker ps

Du solltest postgres und pgadmin mit Status Up sehen.

Containerstatus

Wenn etwas seltsam aussieht, schau in die pgAdmin-Logs:

docker logs pgadmin

Ein gesunder Start sieht so aus:

pgAdmin-Start-Logs

Wenn hier ein Fehler auftaucht, ist es meist einer dieser drei:

• Passwortauthentifizierung fehlgeschlagen: Dein PGADMIN_DEFAULT_PASSWORD fehlt oder ist in der .env-Datei falsch formatiert

• Port bereits belegt: Auf Port 5050 läuft bereits etwas; ändere den Host-Port in deiner Compose-Datei

• Datei oder Verzeichnis nicht gefunden: Der Volume-Pfad ist falsch oder der Container hat keine Schreibrechte

Sobald beide Container laufen und die Logs sauber sind, öffne den Browser und gehe zu http://localhost:5050:

pgAdmin-Login

Melde dich mit der E-Mail und dem Passwort an, die du in PGADMIN_DEFAULT_EMAIL und PGADMIN_DEFAULT_PASSWORD gesetzt hast. Du landest auf dem pgAdmin-Dashboard und kannst deinen PostgreSQL-Server registrieren:

pgAdmin-Startseite

pgAdmin 4 mit deinem PostgreSQL-Container verbinden

Klicke in der pgAdmin-Seitenleiste mit Rechtsklick auf Servers – Register – Server. Ein Dialog öffnet sich mit zwei Tabs, die du ausfüllen musst: General und Connection.

Der Tab General

Gib deinem Server einen aussagekräftigen Namen – zum Beispiel local-dev-postgres. Das ist nur ein Label in pgAdmin, also wähle etwas, das zu deinem Setup passt.

Serverregistrierung – Tab General

Der Tab Connection

Verwende hier nicht localhost. 

Innerhalb eines Docker-Netzwerks bezieht sich localhost auf den Container selbst – nicht auf deinen Host und nicht auf den PostgreSQL-Container. Docker hat ein eigenes internes DNS und löst Containernamen anhand der in deiner docker-compose.yml definierten Servicenamen auf. Wenn dein PostgreSQL-Service also postgres heißt, ist das der Hostname, den du verwendest.

Fülle die Felder wie folgt aus:

• Host name/address: postgres (der Service-Name aus docker-compose.yml)

• Port: 5432

• Maintenance database: der Wert von POSTGRES_DB aus deiner Compose-Datei (z. B. mydb)

• Username: der Wert von POSTGRES_USER (z. B. admin)

• Password: der Wert von POSTGRES_PASSWORD

Klicke auf Save. 

Serverregistrierung – Tab Connection

Wenn alles stimmt, erscheint der Server in der Seitenleiste und du kannst ihn aufklappen und deine Datenbanken ansehen:

Erfolgreiche Serverregistrierung

Das bedeutet: Du bist verbunden.

Das Query Tool nutzen

Da du jetzt verbunden bist, zeige ich dir die Basics von pgAdmin 4 und Postgres allgemein.

Öffne das Query Tool über Tools – Query Tool im oberen Menü. Die Oberfläche hat drei Bereiche:

• Editor: hier schreibst du SQL
• Data Output: hier erscheinen die Ergebnisse nach dem Ausführen
• Messages: hier sendet PostgreSQL Statusmeldungen, Fehler und Ausführungsinfos

Query Tool

SQL schreiben und ausführen

Lass uns eine einfache Tabelle orders anlegen und Daten einfügen. Du kannst jeden Block mit dem Play-Button ausführen oder per Shortcut F5.

Erstelle die Tabelle mit:

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

Füge ein paar Zeilen ein:

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

Und jetzt die Daten abfragen:

SELECT * FROM orders;

Daten abfragen

Die Ergebnisse erscheinen im Data-Output-Bereich als Tabelle. Du kannst Spalten sortieren, ihre Breite anpassen und Zeilen direkt aus dem Grid kopieren.

Den visuellen Query-Plan lesen

Um zu sehen, was beim Ausführen einer Query im Hintergrund passiert, führe EXPLAIN ANALYZE für dein SELECT aus:

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

Explain-Analyze-Ergebnisse

Im Data-Output-Bereich siehst du die Roh-Ausgabe. Aber pgAdmin kann mehr: Klicke in der Toolbar auf Explain – pgAdmin rendert den Query-Plan als interaktiven Graphen.

Query-Plan als Graph

Hier ist es simpel, aber bei Joins oder komplexeren Aggregationen bringt dir das deutlich mehr Einblick.

Das ist wichtig, weil das Lesen der rohen EXPLAIN-Ausgabe langsam und fehleranfällig ist. Der visuelle Plan zeigt sofort, wenn PostgreSQL einen Full Table Scan auf einer großen Tabelle macht oder wenn ein Index existiert, aber nicht genutzt wird.

Dein Datenbankschema verwalten

Die pgAdmin-Seitenleiste gibt dir den vollen Überblick über deine Datenbankstruktur – und erlaubt Änderungen direkt in der GUI.

Die Baumstruktur lautet: Servers – dein Servername – Databases – deine Datenbank – Schemas – public – Tables. Klappe eine Tabelle auf und du siehst Columns, Indexes und Constraints als Unterknoten. Klicke darauf, um Details rechts einzusehen.

Tabellen erstellen und ändern

Um eine neue Tabelle zu erstellen, klicke mit Rechtsklick auf Tables unter deinem Schema und wähle Create – Table. Ein Dialog mit mehreren Tabs öffnet sich.

Tabellen erstellen

Im Tab General vergibst du den Tabellennamen. Wechsle zu Columns, um Spalten hinzuzufügen – pro Zeile legst du Spaltenname, Datentyp, Länge und Nullable fest. Der Tab Constraints kümmert sich um Primary Keys, Foreign Keys und Unique-Constraints.

Um einer bestehenden Tabelle einen Index hinzuzufügen, klappe die Tabelle in der Seitenleiste auf, klicke mit Rechtsklick auf Indexes und wähle Create – Index. Wähle die zu indexierenden Spalten und den Indextyp – btree ist Standard und passt in den meisten Fällen.

Index erstellen

Backup und Restore

Um eine Datenbank zu sichern, gehe zu Tools – Backup. Du musst ein Format wählen:

• Custom: komprimiertes, binäres Format; die flexibelste Option und meist die beste Wahl, da du einzelne Tabellen wiederherstellen kannst
• Plain: ein lesbares SQL-Skript, das du in jedem Texteditor öffnen kannst
• Tar: ein unkomprimiertes Archiv; seltener genutzt, aber für manche Restore-Workflows praktisch

Nachdem du Format und Zielpfad gewählt hast, führt pgAdmin im Hintergrund pg_dump aus und speichert die Datei lokal.

Backup erstellen

Für die Wiederherstellung gehe zu Tools – Restore, wähle deine Backup-Datei und gib die Zieldatenbank an.

Aus Backup wiederherstellen

Falls du dich fragst, wozu das gut ist: Stell dir vor, du testest eine destruktive Migration auf deiner Dev-Datenbank. Mach vorher ein Backup, führe die Migration aus und wenn etwas schiefgeht, stellst du den bekannten Zustand einfach wieder her.

Best Practices für pgAdmin 4 in Docker

pgAdmin 4 zum Laufen zu bringen ist das eine. Es stabil zu betreiben, erfordert ein paar zusätzliche Kniffe. Hier sind praxisnahe Tipps.

Zugangsdaten nicht in der Compose-Datei speichern

Wenn deine docker-compose.yml in die Versionsverwaltung kommt – was meistens der Fall ist – landen hartkodierte Passwörter mit darin. Nutze für Zugangsdaten eine .env-Datei und füge sie zur .gitignore hinzu. In Produktionsumgebungen geh einen Schritt weiter und nutze Docker Secrets, die sensible Werte als Dateien statt als Umgebungsvariablen bereitstellen.

Den pgAdmin-Port niemals öffentlich exposen

Standardmäßig bindet Docker Ports an 0.0.0.0, also an alle Netzwerkschnittstellen – auch öffentliche. Auf einem Remote-Server ist deine pgAdmin-Instanz dann aus dem Internet erreichbar. Binde stattdessen explizit an 127.0.0.1:

ports:
  - "127.0.0.1:5050:5050"

Dadurch ist pgAdmin nur vom Server selbst aus erreichbar. Für entfernten Zugriff nutze einen SSH-Tunnel oder einen Reverse Proxy.

Image-Tags fest pinnen

Mit dpage/pgadmin4:latest ziehst du beim nächsten docker compose pull automatisch eine neue Version. Die kann sich anders verhalten, deine Konfiguration brechen oder unerwartete Änderungen bringen. Nutze lieber einen konkreten Tag wie dpage/pgadmin4:9.13, damit alle im Team exakt dieselbe Version verwenden.

Serververbindungen per servers.json vorladen

Wenn das ganze Team dasselbe Compose-Setup nutzt, soll nicht jede Person den PostgreSQL-Server manuell registrieren müssen. pgAdmin unterstützt eine servers.json, die Verbindungen beim Start vorbefüllt. Binde sie so in den Container ein:

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

So sieht eine minimale servers.json aus:

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

Der Server erscheint beim Start von pgAdmin – ganz ohne manuelle Einrichtung.

Fazit

In diesem Artikel hast du pgAdmin 4 in Docker von Grund auf eingerichtet. Du hast eine Docker-Compose-Datei geschrieben, die PostgreSQL und pgAdmin 4 gemeinsam startet, beide Container über Dockers internes DNS verbunden und die Kernfunktionen von pgAdmin genutzt – das Query Tool, den Schema-Browser sowie den Backup/Restore-Workflow.

Das Grundprinzip ist Reproduzierbarkeit. 

Eine docker-compose.yml, eine servers.json und eine .env-Datei reichen, um einer Teamkollegin oder einem Teamkollegen eine vollständig konfigurierte Datenbankumgebung zu übergeben. So passiert das „Bei mir läuft’s“-Problem nicht mehr.

Wenn du tiefer in Docker und Containerisierung einsteigen willst, schau dir unseren Kurs Intermediate Docker an. Er steckt voller Tipps zu Multi-Stage-Builds, Networking und einem Deep Dive in Compose.