Docker pgAdmin: Cum să configurați o interfață grafică PostgreSQL cu Docker Compose

Un ghid pas cu pas pentru configurarea pgAdmin 4 și PostgreSQL cu Docker Compose, acoperind configurarea containerelor, înregistrarea serverului și funcțiile esențiale pgAdmin, inclusiv Query Tool, browserul de scheme și backup/restaurare.

Actualizat 4 mai 2026 · 10 min. citire

A tot schimba între sesiuni, a memora sintaxa și a spera că nu ați greșit o interogare distructivă devine obositor repede. Nu există un plan vizual al interogării, nici un browser de scheme și nici o modalitate simplă de a face backup unei baze de date. Funcționează, dar e departe de a fi ideal.

pgAdmin 4 rezolvă asta cu o interfață web concepută special pentru PostgreSQL. Iar rularea în Docker înseamnă zero instalare locală. Trebuie doar să porniți containerul.

În acest articol, vă arăt cum să configurați PostgreSQL și pgAdmin 4 cu Docker Compose, să conectați cele două containere și să folosiți Query Tool, browserul de scheme și funcțiile de backup din pgAdmin.

Pentru a putea urmări, aveți nevoie de Docker instalat și în execuție pe mașina dumneavoastră. Dacă sunteți nou în Docker Compose, citiți ghidul nostru pentru a vedea cum simplifică dezvoltarea cu mai multe containere.

Ce este pgAdmin 4?

pgAdmin 4 este o platformă open-source, accesibilă din browser, pentru administrarea și dezvoltarea PostgreSQL. O accesați printr-un browser web, astfel că nu există nicio aplicație desktop de instalat. Vă oferă o interfață grafică pentru a gestiona baze de date, a rula interogări, a inspecta scheme și a gestiona backupuri - totul fără a atinge linia de comandă.

Imaginea Docker oficială este dpage/pgadmin4, întreținută de echipa de dezvoltare pgAdmin.

Rularea pgAdmin 4 în Docker are câteva avantaje reale față de o instalare locală. Primul este portabilitatea - întregul mediu de baze de date se află într-un fișier docker-compose.yml pe care îl puteți partaja cu colegii. Al doilea: fără conflicte de versiuni - pgAdmin rulează în propriul container, complet izolat de orice altceva de pe mașină. Iar când ați terminat, docker compose down îl curăță complet.

pgAdmin 4 vs. alte interfețe grafice pentru PostgreSQL

Există o mulțime de instrumente GUI pentru gestionarea bazelor de date. Iată cum se compară pgAdmin 4 cu două alternative populare.

pgAdmin 4 versus alternative populare

DBeaver și TablePlus sunt instrumente bune, dar niciunul nu are o imagine Docker oficială. Dacă instanța dumneavoastră PostgreSQL rulează deja în Docker, pgAdmin 4 se potrivește perfect - trebuie doar să adăugați un serviciu în docker-compose.yml și totul rulează împreună în aceeași rețea.

Configurarea mediului cu Docker Compose

Cea mai rapidă modalitate de a porni PostgreSQL și pgAdmin 4 împreună este un singur fișier docker-compose.yml. Dacă sunteți la început, Ghidul Docker Compose acoperă elementele de bază. Aici, mă concentrez pe configurația specifică pgAdmin.

Iată fișierul complet pe care îl puteți copia-lipi:

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:

Câmpul depends_on îi spune lui Docker Compose să pornească containerul postgres înainte de pgadmin. Fără acesta, pgAdmin ar putea porni înainte ca PostgreSQL să fie pregătit și ar eșua conectarea. Nu așteaptă ca PostgreSQL să fie complet sănătos - doar ca containerul să pornească. Totuși, e suficient pentru a evita majoritatea condițiilor de cursă.

Variabile de mediu pentru pgAdmin 4

Două variabile de mediu sunt obligatorii:

PGADMIN_DEFAULT_EMAIL - adresa de e-mail cu care vă veți autentifica în interfața web pgAdmin
PGADMIN_DEFAULT_PASSWORD - parola pentru acel cont

A treia este opțională, dar ar trebui specificată:

PGADMIN_LISTEN_PORT - portul pe care pgAdmin ascultă în interiorul containerului. Implicit este 80, dar setarea la 5050 păstrează lucrurile mai clare când mapați porturi.

Totuși, a codifica în clar acreditările în fișierul Compose este o idee proastă, mai ales dacă fișierul ajunge în controlul versiunilor. Mutați-le într-un fișier .env.

Creați un fișier .env în același director cu docker-compose.yml:

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

Apoi referiți variabilele în fișierul 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 detectează fișierele .env când rulați comanda, astfel că nu e nevoie de configurare suplimentară. Doar nu uitați să adăugați .env în .gitignore și acreditările vor rămâne în afara repository-ului.

Volume și persistența datelor

Volumul mapat la /var/lib/pgadmin este locul în care pgAdmin stochează datele, precum datele de sesiune, conexiunile salvate la servere și configurația. Eliminarea acestuia din fișierul compose înseamnă că le veți pierde de fiecare dată când containerul repornește.

În fișierul compose actual, aveți un volum denumit pe care Docker îl gestionează pe mașina gazdă. Datele persistă la reporniri ale containerului, recreări și actualizări ale imaginii - atâta timp cât nu ștergeți explicit volumul cu docker volume rm.

Pornirea stack-ului și accesarea pgAdmin 4

Cu docker-compose.yml pregătit, pornirea stack-ului necesită o singură comandă:

docker compose up -d

Indicatorul -d rulează ambele containere în modul detașat - pornesc în fundal și terminalul rămâne liber. Pentru a verifica dacă ambele containere rulează:

docker ps

Ar trebui să vedeți atât postgres, cât și pgadmin listate cu status Up.

Starea containerelor

Dacă ceva nu arată bine, verificați jurnalele pgAdmin:

docker logs pgadmin

O pornire sănătoasă arată așa:

Jurnalele de pornire pgAdmin

Dacă vedeți o eroare aici, probabil e una dintre aceste trei:

Autentificarea cu parolă a eșuat: PGADMIN_DEFAULT_PASSWORD lipsește sau este greșit în fișierul .env
Portul este deja alocat: altceva rulează pe portul 5050; schimbați portul gazdă în fișierul Compose
Nu există un astfel de fișier sau director: calea volumului este greșită sau containerul nu are permisiunea de a scrie în el

După ce ambele containere sunt pornite și jurnalele arată curat, deschideți browserul și accesați http://localhost:5050:

Pagina de autentificare pgAdmin

Autentificați-vă cu e-mailul și parola setate în PGADMIN_DEFAULT_EMAIL și PGADMIN_DEFAULT_PASSWORD. Veți ajunge în tabloul de bord pgAdmin, gata să înregistrați serverul PostgreSQL:

Pagina principală pgAdmin

Conectarea pgAdmin 4 la containerul dumneavoastră PostgreSQL

În bara laterală pgAdmin, faceți clic dreapta pe Servers - Register - Server. Se deschide un dialog cu două file pe care trebuie să le completați: General și Connection.

Fila General

Dați serverului un nume semnificativ - ceva de genul local-dev-postgres. Este doar o etichetă în pgAdmin, așa că alegeți orice are sens pentru configurarea dumneavoastră.

Înregistrare server - fila General

Fila Connection

Nu folosiți localhost aici.

Într-o rețea Docker, localhost se referă la containerul însuși - nu la mașina gazdă și nici la containerul PostgreSQL. Docker are propriul DNS intern și rezolvă numele containerelor folosind numele de servicii definite în docker-compose.yml. Așadar, dacă serviciul PostgreSQL se numește postgres, acesta este hostname-ul pe care îl folosiți.

Completați câmpurile astfel:

Host name/address: postgres (numele serviciului din docker-compose.yml)
Port: 5432
Maintenance database: valoarea POSTGRES_DB din fișierul Compose (de ex., mydb)
Username: valoarea POSTGRES_USER (de ex., admin)
Password: valoarea POSTGRES_PASSWORD

Faceți clic pe Save.

Înregistrare server - fila Connection

Dacă totul este corect, serverul va apărea în bara laterală și îl veți putea extinde pentru a vă vedea bazele de date:

Înregistrare server reușită

Asta înseamnă că sunteți conectat.

Utilizarea Query Tool

Acum că sunteți conectat, vă arăt elementele de bază ale pgAdmin 4 și ale Postgres, în general.

Deschideți Query Tool făcând clic pe Tools - Query Tool din meniul de sus. Interfața are trei panouri:

Editor: unde scrieți SQL
Data Output: unde apar rezultatele după ce rulați o interogare
Messages: unde PostgreSQL trimite mesaje de stare, erori și informații de execuție

Query tool

Scrierea și rularea SQL

Să creăm un tabel simplu orders și să adăugăm niște date. Puteți rula fiecare bloc apăsând butonul Play sau tasta F5, care este o comandă rapidă.

Rulați asta pentru a crea tabelul:

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

Introduceți câteva rânduri:

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

Și acum interogați datele:

SELECT * FROM orders;

Interogarea datelor

Rezultatele apar în panoul Data Output sub formă de tabel. Puteți sorta coloanele, le puteți redimensiona și puteți copia rânduri direct din grid.

Citirea planului vizual al interogării

Pentru a vedea ce se întâmplă în culise când rulați o interogare, rulați EXPLAIN ANALYZE pe instrucțiunea SELECT:

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

Rezultatele Explain Analyze

Panoul Data Output afișează rezultatul brut. Dar pgAdmin are o opțiune mai bună. Faceți clic pe butonul Explain din bara de instrumente - iar pgAdmin redă planul interogării ca un grafic interactiv.

Planul interogării ca grafic

Acum, este simplu pentru această interogare, dar veți obține mult mai mult când faceți join între tabele sau realizați agregări de date mai complexe.

Acest lucru contează deoarece citirea ieșirii brute EXPLAIN este lentă și predispusă la erori. Planul vizual face evident când PostgreSQL face un full table scan pe un tabel mare sau când există un index dar nu este folosit.

Gestionarea schemei bazei de date

Bara laterală a pgAdmin oferă o vedere completă a structurii bazei de date - și vă permite să o modificați prin interfața grafică.

Arborele din bara laterală este: Servers - numele serverului - Databases - baza de date - Schemas - public - Tables. Extindeți orice tabel și veți vedea Columns, Indexes și Constraints listate ca noduri copil. Faceți clic pe oricare pentru a inspecta detaliile în panoul din dreapta.

Crearea și modificarea tabelelor

Pentru a crea un tabel nou, faceți clic dreapta pe Tables din schema dumneavoastră și selectați Create - Table. Se deschide un dialog cu câteva file.

Crearea tabelelor

Fila General este locul unde setați numele tabelului. Treceți la fila Columns pentru a adăuga coloanele - fiecare rând vă permite să setați numele coloanei, tipul de date, lungimea și dacă permite valori nule. Fila Constraints se ocupă de chei primare, chei externe și constrângeri unice.

Pentru a adăuga un index la un tabel existent, extindeți tabelul în bara laterală, faceți clic dreapta pe Indexes și selectați Create - Index. Alegeți coloanele de indexat și tipul de index - btree este implicit și funcționează în majoritatea cazurilor.

Crearea unui index

Backup și restaurare

Pentru a face backup unei baze de date, mergeți la Tools - Backup. Va trebui să alegeți un format:

Custom: format binar comprimat; cea mai flexibilă opțiune și cea mai bună alegere în majoritatea cazurilor, deoarece puteți restaura tabele individuale din el
Plain: un script SQL simplu pe care îl puteți deschide și citi în orice editor de text
Tar: o arhivă necomprimată; mai puțin comună, dar utilă pentru unele fluxuri de lucru de restaurare

După ce selectați un format și o cale de destinație, pgAdmin rulează pg_dump în fundal și salvează fișierul pe mașina locală.

Crearea unui backup

Pentru restaurare, mergeți la Tools - Restore, selectați fișierul de backup și indicați baza de date țintă.

Restaurarea dintr-un backup

Dacă vă întrebați de ce este util, imaginați-vă că testați o migrare distructivă pe baza de date de dezvoltare. Faceți întâi un backup, rulați migrarea și, dacă ceva se strică, restaurați backupul pentru a reveni la o stare cunoscută.

Bune practici pentru rularea pgAdmin 4 în Docker

Să porniți pgAdmin 4 este una. Dar pentru a-l menține să funcționeze lin, trebuie să știți câteva lucruri în plus. Iată câteva sfaturi practice.

Țineți acreditările în afara fișierului Compose

Dacă docker-compose.yml ajunge în controlul versiunilor - iar de obicei ajunge - parolele codificate în clar îl însoțesc. Folosiți un fișier .env pentru acreditări și adăugați-l în .gitignore. Pentru mediile de producție, mergeți mai departe și folosiți Docker secrets, care montează valorile sensibile ca fișiere, nu ca variabile de mediu.

Nu expuneți niciodată public portul pgAdmin

Implicit, Docker leagă porturile la 0.0.0.0, ceea ce înseamnă orice interfață de rețea - inclusiv cele publice. Pe un server la distanță, asta face instanța pgAdmin accesibilă de pe internet. Legați explicit la 127.0.0.1 în schimb:

ports:
  - "127.0.0.1:5050:5050"

Astfel, pgAdmin devine accesibil doar de pe serverul însuși. Folosiți un tunel SSH sau un reverse proxy dacă aveți nevoie de acces de la distanță.

Înghețați etichetele imaginilor

Folosirea dpage/pgadmin4:latest va trage o versiune nouă data viitoare când cineva rulează docker compose pull. Acea versiune nouă s-ar putea comporta diferit, să vă strice configurația sau să introducă schimbări neașteptate. Folosiți o etichetă specifică precum dpage/pgadmin4:9.13 astfel încât toți colegii să ruleze exact aceeași versiune.

Preîncărcați conexiunile serverului cu `servers.json`

Dacă întreaga echipă împarte aceeași configurare Compose, nu îi puneți pe toți să înregistreze serverul PostgreSQL după pornirea stack-ului. pgAdmin acceptă un fișier servers.json care pre-populează conexiunile la pornire. Montați-l în container astfel:

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

Iată cum arată un servers.json minim:

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

Serverul va apărea la pornirea pgAdmin - fără setare manuală.

Concluzie

În acest articol, v-am prezentat configurarea de la zero a pgAdmin 4 în Docker. Ați scris un fișier Docker Compose care aduce împreună PostgreSQL și pgAdmin 4, ați conectat cele două containere folosind DNS-ul intern al Docker și ați folosit funcțiile de bază ale pgAdmin - Query Tool, browserul de scheme și fluxul de backup/restaurare.

Principiul de bază aici este reproductibilitatea.

Un fișier docker-compose.yml, un servers.json și un fișier .env sunt tot ce vă trebuie pentru a oferi unui coleg un mediu de baze de date complet configurat. Astfel, problema „la mine funcționează” nu va mai apărea niciodată.

Pentru a aprofunda subiectul Docker și containerizarea, consultați cursul nostru Intermediate Docker. Este plin de sfaturi utile despre build-uri multi-stage, rețelistică și o analiză detaliată a Compose.