Docker pgAdmin: jak skonfigurować GUI dla PostgreSQL z Docker Compose

Przewodnik krok po kroku po konfiguracji pgAdmin 4 i PostgreSQL z Docker Compose, obejmujący konfigurację kontenerów, rejestrację serwera oraz kluczowe funkcje pgAdmin, w tym Query Tool, przeglądarkę schematów i kopie zapasowe/przywracanie.

Zaktualizowano 4 maj 2026 · 10 min Czytać

Przełączanie się między sesjami, zapamiętywanie składni i liczenie na to, że w niszczącym zapytaniu nie ma literówki, szybko się nudzi. Brak wizualnego planu zapytań, przeglądarki schematów i prostego sposobu tworzenia kopii zapasowych bazy. Działa, ale jest dalekie od ideału.

pgAdmin 4 rozwiązuje te problemy dzięki interfejsowi GUI w przeglądarce, zbudowanemu specjalnie dla PostgreSQL. A uruchomienie go w Dockerze oznacza zerową instalację lokalną. Wystarczy uruchomić kontener.

W tym artykule pokażę, jak skonfigurować PostgreSQL i pgAdmin 4 z Docker Compose, połączyć oba kontenery oraz używać Query Tool, przeglądarki schematów i funkcji kopii zapasowych w pgAdmin.

Aby podążać krok po kroku, potrzebne będzie zainstalowane i uruchomione środowisko Docker na Państwa komputerze. Jeśli to pierwszy kontakt z Docker Compose, proszę zajrzeć do naszego przewodnika, aby sprawdzić, jak upraszcza pracę z wieloma kontenerami.

Czym jest pgAdmin 4?

pgAdmin 4 to otwartoźródłowa, przeglądarkowa platforma administracyjno-rozwojowa dla PostgreSQL. Dostęp odbywa się przez przeglądarkę, więc nie trzeba instalować aplikacji desktopowej. Zapewnia GUI do zarządzania bazami, uruchamiania zapytań, przeglądania schematów i obsługi kopii zapasowych — wszystko bez użycia wiersza poleceń.

Oficjalny obraz Dockera to dpage/pgadmin4, utrzymywany przez zespół deweloperski pgAdmin.

Uruchamianie pgAdmin 4 w Dockerze ma kilka realnych zalet w porównaniu z instalacją lokalną. Po pierwsze, przenośność — całe środowisko bazodanowe mieści się w pliku docker-compose.yml, który można udostępnić zespołowi. Po drugie, brak konfliktów wersji — pgAdmin działa w swoim własnym kontenerze, całkowicie odizolowany od reszty systemu. A gdy skończą Państwo pracę, docker compose down czyści wszystko.

pgAdmin 4 vs. inne GUI dla PostgreSQL

Nie brakuje narzędzi GUI do zarządzania bazami danych. Oto jak pgAdmin 4 wypada na tle dwóch popularnych alternatyw.

pgAdmin 4 na tle popularnych alternatyw

DBeaver i TablePlus to dobre narzędzia, ale żadne z nich nie ma oficjalnego obrazu Dockera. Jeśli Państwa instancja PostgreSQL już działa w Dockerze, pgAdmin 4 jest świetnym wyborem — wystarczy dodać jedną usługę do docker-compose.yml i wszystko działa razem w tej samej sieci.

Konfiguracja środowiska za pomocą Docker Compose

Najszybszym sposobem uruchomienia PostgreSQL i pgAdmin 4 razem jest pojedynczy plik docker-compose.yml. Jeśli to nowy temat, nasz przewodnik po Docker Compose omawia podstawy. Tutaj skupię się na konfiguracji specyficznej dla pgAdmin.

Oto kompletny plik do skopiowania i wklejenia:

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:

Pole depends_on informuje Docker Compose, aby uruchomił kontener postgres przed pgadmin. Bez tego pgAdmin mógłby wystartować, zanim PostgreSQL będzie gotowy, i nie uda się połączenie. Nie czeka to na pełne uzdrowienie PostgreSQL — tylko na start kontenera. To jednak zwykle wystarcza, aby uniknąć większości wyścigów.

Zmienne środowiskowe pgAdmin 4

Dwie zmienne środowiskowe są wymagane:

PGADMIN_DEFAULT_EMAIL — adres e-mail używany do logowania do interfejsu webowego pgAdmin
PGADMIN_DEFAULT_PASSWORD — hasło dla tego konta

Trzecia jest opcjonalna, ale warto ją ustawić:

PGADMIN_LISTEN_PORT — port, na którym pgAdmin nasłuchuje wewnątrz kontenera. Domyślnie 80, ale ustawienie na 5050 upraszcza mapowanie portów.

Niemniej jednak twarde wpisywanie poświadczeń w pliku Compose to zły pomysł, zwłaszcza jeśli plik trafi do systemu kontroli wersji. Proszę przenieść je do pliku .env.

Proszę utworzyć plik .env w tym samym katalogu co docker-compose.yml:

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

Następnie proszę odwołać się do zmiennych w pliku 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 automatycznie odczytuje pliki .env przy uruchamianiu polecenia, więc nie są potrzebne dodatkowe ustawienia. Wystarczy dodać .env do .gitignore, a poświadczenia nie trafią do repozytorium.

Wolumeny i trwałość danych

Wolumen zmapowany do /var/lib/pgadmin to miejsce, w którym pgAdmin przechowuje dane, takie jak dane sesji, zapisane połączenia z serwerami i konfigurację. Usunięcie tego wpisu z pliku compose oznacza utratę wszystkiego przy każdym restarcie kontenera.

W obecnym pliku compose używany jest nazwany wolumen zarządzany przez Dockera na Państwa hoście. Dane przetrwają restarty kontenera, jego ponowne tworzenie i aktualizacje obrazu — dopóki wolumen nie zostanie jawnie usunięty poleceniem docker volume rm.

Uruchamianie stosu i dostęp do pgAdmin 4

Mając gotowy plik docker-compose.yml, uruchomienie stosu wymaga jednego polecenia:

docker compose up -d

Przełącznik -d uruchamia oba kontenery w trybie odłączonym — startują w tle, a terminal pozostaje wolny. Aby sprawdzić, czy oba kontenery działają:

docker ps

Powinny być widoczne zarówno postgres, jak i pgadmin ze statusem Up.

Status kontenerów

Jeśli coś wygląda nie tak, proszę sprawdzić logi pgAdmin:

docker logs pgadmin

Prawidłowy start wygląda tak:

Logi startowe pgAdmin

Jeśli pojawi się błąd, najpewniej będzie to jeden z trzech:

Niepowodzenie uwierzytelnienia hasła: w pliku .env brakuje wartości PGADMIN_DEFAULT_PASSWORD lub jest ona nieprawidłowa
Port jest już zajęty: coś innego działa na porcie 5050; proszę zmienić port hosta w pliku Compose
Brak pliku lub katalogu: ścieżka wolumenu jest nieprawidłowa albo kontener nie ma uprawnień do zapisu

Gdy oba kontenery działają, a logi są czyste, proszę otworzyć przeglądarkę i przejść do http://localhost:5050:

Strona logowania pgAdmin

Proszę zalogować się adresem e-mail i hasłem ustawionymi w PGADMIN_DEFAULT_EMAIL oraz PGADMIN_DEFAULT_PASSWORD. Zostaną Państwo przeniesieni do pulpitu pgAdmin, gotowego do zarejestrowania serwera PostgreSQL:

Strona główna pgAdmin

Łączenie pgAdmin 4 z kontenerem PostgreSQL

W panelu bocznym pgAdmin proszę kliknąć prawym przyciskiem myszy Servers - Register - Server. Otworzy się okno z dwoma zakładkami do uzupełnienia: General i Connection.

Zakładka General

Proszę nadać serwerowi znaczącą nazwę — np. local-dev-postgres. To tylko etykieta w pgAdmin, więc proszę wybrać cokolwiek, co ma sens w Państwa środowisku.

Rejestracja serwera — karta General

Zakładka Connection

Proszę tutaj nie używać localhost.

W sieci Dockera localhost odnosi się do samego kontenera — nie do hosta ani kontenera PostgreSQL. Docker ma własny wewnętrzny DNS i rozwiązuje nazwy kontenerów według nazw usług zdefiniowanych w docker-compose.yml. Jeśli więc Państwa usługa PostgreSQL nazywa się postgres, to jest to nazwa hosta, której należy użyć.

Proszę uzupełnić pola w następujący sposób:

Host name/address: postgres (nazwa usługi z docker-compose.yml)
Port: 5432
Maintenance database: wartość POSTGRES_DB z pliku Compose (np. mydb)
Username: wartość POSTGRES_USER (np. admin)
Password: wartość POSTGRES_PASSWORD

Proszę kliknąć Save.

Rejestracja serwera — karta Connection

Jeśli wszystko jest poprawne, serwer pojawi się w panelu bocznym i będzie można go rozwinąć, aby zobaczyć bazy danych:

Pomyślna rejestracja serwera

To oznacza, że połączenie działa.

Korzystanie z Query Tool

Skoro jest już połączenie, pokażę podstawy pgAdmin 4 i ogólnie Postgresa.

Proszę otworzyć Query Tool, wybierając Tools - Query Tool z górnego menu. Interfejs ma trzy panele:

Editor: miejsce do pisania SQL
Data Output: miejsce wyświetlania wyników po uruchomieniu zapytania
Messages: miejsce, do którego PostgreSQL wysyła komunikaty statusu, błędy i informacje o wykonaniu

Narzędzie Query

Pisanie i uruchamianie SQL

Utwórzmy prostą tabelę orders i dodajmy trochę danych. Każdy blok można uruchomić przyciskiem Play lub skrótem F5.

Proszę uruchomić to, aby utworzyć tabelę:

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

Proszę wstawić kilka wierszy:

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

A teraz zapytajmy dane:

SELECT * FROM orders;

Zapytanie o dane

Wyniki pojawią się w panelu Data Output jako tabela. Można sortować kolumny, zmieniać ich rozmiar i kopiować wiersze bezpośrednio z siatki.

Odczytywanie wizualnego planu zapytań

Aby zobaczyć, co dzieje się w tle podczas uruchamiania zapytania, proszę wykonać EXPLAIN ANALYZE dla instrukcji SELECT:

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

Wyniki Explain Analyze

Panel Data Output pokazuje surowe dane wyjściowe. Ale pgAdmin ma lepszą opcję. Proszę kliknąć przycisk Explain na pasku narzędzi — pgAdmin wyrenderuje plan zapytania jako interaktywny wykres.

Plan zapytania jako wykres

Tutaj jest to proste zapytanie, ale przy złączeniach tabel lub bardziej złożonych agregacjach widać znacznie więcej.

Ma to znaczenie, ponieważ czytanie surowego wyjścia EXPLAIN jest wolne i podatne na błędy. Wizualny plan jasno pokazuje, kiedy PostgreSQL wykonuje pełne skanowanie dużej tabeli albo gdy istnieje indeks, który nie jest używany.

Zarządzanie schematem bazy danych

Panel boczny pgAdmin daje pełny widok struktury bazy — i pozwala ją modyfikować przez GUI.

Drzewo w panelu bocznym przebiega: Servers — nazwa serwera — Databases — Państwa baza — Schemas — public — Tables. Po rozwinięciu dowolnej tabeli zobaczą Państwo jej Columns, Indexes i Constraints jako węzły podrzędne. Kliknięcie któregoś z nich wyświetla szczegóły w panelu po prawej.

Tworzenie i modyfikowanie tabel

Aby utworzyć nową tabelę, proszę kliknąć prawym przyciskiem myszy Tables w ramach schematu i wybrać Create - Table. Otworzy się okno z kilkoma zakładkami.

Tworzenie tabel

Na karcie General ustawia się nazwę tabeli. Proszę przejść do karty Columns, aby dodać kolumny — każdy wiersz pozwala ustawić nazwę kolumny, typ danych, długość i to, czy może mieć wartość NULL. Zakładka Constraints obsługuje klucze główne, obce i ograniczenia unikalności.

Aby dodać indeks do istniejącej tabeli, proszę rozwinąć tabelę w panelu bocznym, kliknąć prawym przyciskiem myszy Indexes i wybrać Create - Index. Następnie wybrać kolumny do zindeksowania i typ indeksu — btree jest domyślny i sprawdza się w większości przypadków.

Tworzenie indeksu

Kopia zapasowa i przywracanie

Aby wykonać kopię zapasową bazy, proszę przejść do Tools - Backup. Należy wybrać format:

Custom: skompresowany, binarny format; najbardziej elastyczny i zwykle najlepszy, ponieważ pozwala przywracać pojedyncze tabele
Plain: zwykły skrypt SQL, który można otworzyć i przeczytać w dowolnym edytorze tekstu
Tar: nieskompresowane archiwum; rzadziej używane, ale przydatne w niektórych scenariuszach przywracania

Po wybraniu formatu i ścieżki docelowej pgAdmin uruchamia w tle pg_dump i zapisuje plik na lokalnym komputerze.

Tworzenie kopii zapasowej

Aby przywrócić, proszę przejść do Tools - Restore, wybrać plik kopii zapasowej i wskazać docelową bazę danych.

Przywracanie z kopii zapasowej

Jeśli zastanawiają się Państwo, po co to wszystko, proszę wyobrazić sobie testowanie niszczącej migracji na bazie deweloperskiej. Najpierw proszę zrobić kopię zapasową, uruchomić migrację, a jeśli coś się zepsuje — przywrócić kopię, by wrócić do znanego stanu.

Najlepsze praktyki uruchamiania pgAdmin 4 w Dockerze

Uruchomienie pgAdmin 4 to jedno. Utrzymanie go w dobrej kondycji wymaga jednak kilku dodatkowych informacji. Oto kilka praktycznych wskazówek.

Trzymaj poświadczenia poza plikiem Compose

Jeśli docker-compose.yml trafi do systemu kontroli wersji — a zwykle tak jest — twardo wpisane hasła trafią tam razem z nim. Proszę używać pliku .env na poświadczenia i dodać go do .gitignore. W środowiskach produkcyjnych warto pójść dalej i użyć sekretów Dockera, które montują wrażliwe wartości jako pliki zamiast zmiennych środowiskowych.

Nigdy nie wystawiaj publicznie portu pgAdmin

Domyślnie Docker wiąże porty z 0.0.0.0, czyli wszystkimi interfejsami sieciowymi — także publicznymi. Na zdalnym serwerze oznacza to, że instancja pgAdmin jest dostępna z internetu. Proszę jawnie powiązać z 127.0.0.1:

ports:
  - "127.0.0.1:5050:5050"

Dzięki temu pgAdmin będzie dostępny tylko z samego serwera. Jeśli potrzebny jest zdalny dostęp, proszę użyć tunelu SSH lub reverse proxy.

Przypinaj tagi obrazów

Użycie dpage/pgadmin4:latest spowoduje pobranie nowej wersji przy kolejnym docker compose pull. Nowa wersja może zachowywać się inaczej, zepsuć konfigurację lub wprowadzić nieoczekiwane zmiany. Proszę używać konkretnego tagu, np. dpage/pgadmin4:9.13, aby każdy członek zespołu korzystał z dokładnie tej samej wersji.

Wstępnie ładuj połączenia serwerów za pomocą `servers.json`

Jeśli cały zespół korzysta z tego samego zestawu Compose, nie każcie każdemu rejestrować serwera PostgreSQL po uruchomieniu stosu. pgAdmin obsługuje plik servers.json, który wstępnie wypełnia połączenia przy starcie. Proszę zamontować go w kontenerze w ten sposób:

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

Tak wygląda minimalny servers.json:

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

Serwer pojawi się po starcie pgAdmin — bez ręcznej konfiguracji.

Podsumowanie

W tym artykule pokazałem, jak od zera skonfigurować pgAdmin 4 w Dockerze. Przygotowali Państwo plik Docker Compose uruchamiający razem PostgreSQL i pgAdmin 4, połączyli kontenery z użyciem wewnętrznego DNS Dockera oraz skorzystali z kluczowych funkcji pgAdmin — Query Tool, przeglądarki schematów i procesu kopii zapasowych/przywracania.

Kluczową zasadą jest tu odtwarzalność.

Pliki docker-compose.yml, servers.json i .env to wszystko, czego potrzeba, by przekazać współpracownikowi w pełni skonfigurowane środowisko bazodanowe. Dzięki temu problem „u mnie działa” przestanie się pojawiać.

Aby zgłębić temat Dockera i konteneryzacji, proszę sprawdzić nasz kurs Intermediate Docker. Zawiera mnóstwo przydatnych wskazówek dotyczących wieloetapowych buildów, sieci i dogłębnego omówienia Compose.