Docker pgAdmin: come configurare una GUI per PostgreSQL con Docker Compose

Passare da una sessione all’altra, memorizzare la sintassi e sperare di non aver digitato male una query distruttiva stanca in fretta. Niente piano di esecuzione visuale, niente browser dello schema e nessun modo semplice per fare il backup di un database. Funziona, ma è lontano dall’ideale.

pgAdmin 4 risolve il problema con una GUI basata su browser progettata apposta per PostgreSQL. E farlo girare in Docker significa zero installazione locale: basta avviare il container.

In questo articolo ti mostro come configurare PostgreSQL e pgAdmin 4 con Docker Compose, collegare i due container e usare il Query Tool, il browser dello schema e le funzioni di backup di pgAdmin.

Per seguire, ti serve Docker installato e in esecuzione sulla tua macchina. Se sei alle prime armi con Docker Compose, leggi la nostra guida per vedere come semplifica lo sviluppo multi-container.

Cos’è pgAdmin 4?

pgAdmin 4 è una piattaforma open-source, basata su browser, per amministrazione e sviluppo su PostgreSQL. Lo apri dal browser, quindi non c’è alcuna app desktop da installare. Ti offre una GUI per gestire database, eseguire query, ispezionare gli schemi e gestire i backup — il tutto senza toccare la riga di comando.

L’immagine Docker ufficiale è dpage/pgadmin4, mantenuta dal team di sviluppo di pgAdmin.

Eseguire pgAdmin 4 in Docker ha un paio di veri vantaggi rispetto a un’installazione locale. Il primo è la portabilità: tutto l’ambiente database vive in un file docker-compose.yml che puoi condividere con il team. Il secondo è l’assenza di conflitti di versione: pgAdmin gira nel suo container, completamente isolato da tutto il resto sulla tua macchina. E quando hai finito, docker compose down pulisce tutto.

pgAdmin 4 vs. altre GUI per PostgreSQL

Gli strumenti GUI per la gestione dei database non mancano. Ecco come si confronta pgAdmin 4 con due alternative popolari.

pgAdmin 4 rispetto ad alternative popolari

DBeaver e TablePlus sono ottimi strumenti, ma nessuno dei due ha un’immagine Docker ufficiale. Se la tua istanza PostgreSQL è già in esecuzione in Docker, pgAdmin 4 è la scelta ideale: ti basta aggiungere un servizio al tuo docker-compose.yml e tutto gira insieme nella stessa rete.

Configurare l’ambiente con Docker Compose

Il modo più veloce per far girare insieme PostgreSQL e pgAdmin 4 è un singolo file docker-compose.yml. Se sei nuovo all’argomento, la nostra Guida a Docker Compose copre i fondamentali. Qui mi concentro sulla configurazione specifica di pgAdmin.

Ecco il file completo da copiare e incollare:

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:

Il campo depends_on dice a Docker Compose di avviare il container postgres prima di pgadmin. Senza questo, pgAdmin potrebbe partire prima che PostgreSQL sia pronto e non riuscire a connettersi. Non aspetta che PostgreSQL sia completamente “healthy” — solo che il container si avvii. È comunque sufficiente per evitare la maggior parte delle race condition.

Variabili d’ambiente di pgAdmin 4

Due variabili d’ambiente sono obbligatorie:

• PGADMIN_DEFAULT_EMAIL - l’indirizzo email con cui effettuerai l’accesso all’interfaccia web di pgAdmin
• PGADMIN_DEFAULT_PASSWORD - la password per quell’account

Una terza è opzionale ma è consigliabile specificarla:

• PGADMIN_LISTEN_PORT - la porta su cui pgAdmin ascolta all’interno del container. Di default è 80, ma impostarla a 5050 rende più ordinato il mapping delle porte.

Detto questo, inserire le credenziali in chiaro nel file Compose è una cattiva idea, soprattutto se il file finisce nel version control. Spostale in un file .env.

Crea un file .env nella stessa directory del tuo docker-compose.yml:

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

Poi riferisci le variabili nel file 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 rileva i file .env quando esegui il comando, quindi non serve altra configurazione. Ricordati solo di aggiungere .env al tuo .gitignore e le credenziali resteranno fuori dal repo.

Volumi e persistenza dei dati

Il volume mappato su /var/lib/pgadmin è dove pgAdmin salva i dati, come sessioni, connessioni ai server salvate e configurazione. Rimuoverlo dal compose file significa perdere tutto a ogni riavvio del container.

Nel file compose attuale, hai un volume con nome gestito da Docker sulla tua macchina host. I dati sopravvivono a riavvii del container, ricreazioni e aggiornamenti dell’immagine — finché non elimini esplicitamente il volume con docker volume rm.

Avviare lo stack e accedere a pgAdmin 4

Con il tuo docker-compose.yml pronto, avviare lo stack richiede un solo comando:

docker compose up -d

Il flag -d esegue entrambi i container in modalità detached — partono in background e il terminale resta libero. Per verificare che entrambi i container siano in esecuzione:

docker ps

Dovresti vedere sia postgres che pgadmin elencati con stato Up.

Stato dei container

Se qualcosa non torna, controlla i log di pgAdmin:

docker logs pgadmin

Un avvio sano appare così:

Log di avvio di pgAdmin

Se vedi un errore qui, probabilmente è uno di questi tre:

• Autenticazione con password fallita: il tuo PGADMIN_DEFAULT_PASSWORD manca o è malformato nel file .env

• Port already allocated: qualcos’altro è in esecuzione sulla porta 5050; cambia la porta host nel tuo Compose file

• No such file or directory: il path del volume è sbagliato o il container non ha i permessi per scriverci

Quando entrambi i container sono su e i log sono puliti, apri il browser e vai su http://localhost:5050:

Pagina di login di pgAdmin

Accedi con l’email e la password impostate in PGADMIN_DEFAULT_EMAIL e PGADMIN_DEFAULT_PASSWORD. Arriverai alla dashboard di pgAdmin, pronto per registrare il tuo server PostgreSQL:

Home page di pgAdmin

Collegare pgAdmin 4 al tuo container PostgreSQL

Nella sidebar di pgAdmin, fai clic destro su Servers - Register - Server. Si apre una finestra con due tab da compilare: General e Connection.

La tab General

Dai al server un nome significativo — qualcosa come local-dev-postgres. È solo un’etichetta dentro pgAdmin, quindi scegli ciò che ha senso per il tuo setup.

Registrazione server - Tab General

La tab Connection

Non usare localhost qui. 

All’interno di una rete Docker, localhost si riferisce al container stesso — non alla tua macchina host, né al container PostgreSQL. Docker ha un DNS interno che risolve i nomi dei container usando i service name definiti nel tuo docker-compose.yml. Quindi, se il servizio PostgreSQL si chiama postgres, quello è l’hostname da usare.

Compila i campi così:

• Host name/address: postgres (il nome del servizio da docker-compose.yml)

• Port: 5432

• Maintenance database: il valore di POSTGRES_DB dal tuo Compose file (es. mydb)

• Username: il valore di POSTGRES_USER (es. admin)

• Password: il valore di POSTGRES_PASSWORD

Fai clic su Save. 

Registrazione server - Tab Connection

Se è tutto corretto, il server apparirà nella sidebar e potrai espanderlo e vedere i tuoi database:

Registrazione del server riuscita

Questo significa che sei connesso.

Usare il Query Tool

Ora che sei connesso, ti mostro le basi di pgAdmin 4 e di Postgres in generale.

Apri il Query Tool facendo clic su Tools - Query Tool dal menu in alto. L’interfaccia ha tre pannelli:

• Editor: dove scrivi SQL
• Data Output: dove compaiono i risultati dopo l’esecuzione di una query
• Messages: dove PostgreSQL invia messaggi di stato, errori e informazioni di esecuzione

Query tool

Scrivere ed eseguire SQL

Creiamo una semplice tabella orders e aggiungiamo qualche dato. Puoi eseguire ogni blocco cliccando il pulsante Play o premendo F5, che è una scorciatoia.

Esegui questo per creare la tabella:

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

Inserisci alcune righe:

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

E ora interroga i dati:

SELECT * FROM orders;

Query dei dati

I risultati compaiono nel pannello Data Output come tabella. Puoi ordinare le colonne, ridimensionarle e copiare le righe direttamente dalla griglia.

Leggere il piano di esecuzione visuale

Per vedere cosa succede dietro le quinte quando esegui una query, lancia EXPLAIN ANALYZE sulla tua istruzione SELECT:

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

Risultati di Explain Analyze

Il pannello Data Output mostra l’output grezzo. Ma pgAdmin ha un’opzione migliore. Clicca il pulsante Explain nella toolbar — e pgAdmin renderizza il piano di esecuzione come grafico interattivo.

Piano di query come grafico

Qui è semplice, ma otterrai molto di più quando fai join tra tabelle o esegui aggregazioni più complesse.

Questo è importante perché leggere l’output grezzo di EXPLAIN è lento e soggetto a errori. Il piano visuale rende evidente quando PostgreSQL fa una scansione completa di una tabella grande o quando esiste un indice ma non viene usato.

Gestire lo schema del database

La sidebar di pgAdmin ti dà una vista completa della struttura del database — e ti permette di modificarla tramite GUI.

L’albero della sidebar è: Servers - il nome del tuo server - Databases - il tuo database - Schemas - public - Tables. Espandi qualsiasi tabella e vedrai Columns, Indexes e Constraints elencati come nodi figli. Clicca su uno di essi per ispezionarne i dettagli nel pannello di destra.

Creare e modificare tabelle

Per creare una nuova tabella, fai clic destro su Tables sotto il tuo schema e seleziona Create - Table. Si apre una finestra con alcune tab.

Creazione di tabelle

La tab General è dove imposti il nome della tabella. Passa alla tab Columns per aggiungere le colonne: ogni riga ti permette di definire il nome, il tipo di dato, la lunghezza e se è nullable. La tab Constraints gestisce chiavi primarie, chiavi esterne e vincoli univoci.

Per aggiungere un indice a una tabella esistente, espandi la tabella nella sidebar, fai clic destro su Indexes e seleziona Create - Index. Scegli le colonne da indicizzare e il tipo di indice — btree è il default e va bene nella maggior parte dei casi.

Creazione di un indice

Backup e ripristino

Per eseguire il backup di un database, vai su Tools - Backup. Dovrai scegliere un formato:

• Custom: formato binario compresso; è l’opzione più flessibile e la scelta migliore nella maggior parte dei casi perché consente di ripristinare tabelle individuali
• Plain: uno script SQL in chiaro che puoi aprire e leggere con qualsiasi editor di testo
• Tar: un archivio non compresso; meno comune ma utile per alcuni flussi di ripristino

Dopo aver selezionato formato e percorso di destinazione, pgAdmin esegue pg_dump in background e salva il file sulla tua macchina locale.

Creazione di un backup

Per ripristinare, vai su Tools - Restore, seleziona il file di backup e indica il database di destinazione.

Ripristino da un backup

Se ti stai chiedendo a cosa serva, immagina che stai testando una migrazione distruttiva sul tuo database di sviluppo. Fai prima un backup, esegui la migrazione e, se qualcosa si rompe, ripristina il backup per tornare a uno stato noto.

Best practice per eseguire pgAdmin 4 in Docker

Far partire pgAdmin 4 è un conto. Tenerlo in funzione senza intoppi richiede qualche accortezza in più. Ecco alcuni consigli pratici.

Tieni le credenziali fuori dal tuo file Compose

Se il tuo docker-compose.yml finisce nel version control — e di solito succede — le password hardcoded ci finiscono insieme. Usa un file .env per le credenziali e aggiungilo al .gitignore. In produzione, fai un passo in più e usa i Docker secrets, che montano i valori sensibili come file anziché variabili d’ambiente.

Non esporre mai pubblicamente la porta di pgAdmin

Per impostazione predefinita, Docker associa le porte a 0.0.0.0, cioè a qualsiasi interfaccia di rete — incluse quelle pubbliche. Su un server remoto, questo rende la tua istanza pgAdmin raggiungibile da internet. Associala esplicitamente a 127.0.0.1 invece:

ports:
  - "127.0.0.1:5050:5050"

In questo modo pgAdmin è accessibile solo dal server stesso. Usa un tunnel SSH o un reverse proxy se ti serve l’accesso remoto.

Blocca i tag delle immagini

Usare dpage/pgadmin4:latest scaricherà una nuova versione la prossima volta che qualcuno esegue docker compose pull. Quella nuova versione potrebbe comportarsi diversamente, rompere la tua configurazione o introdurre cambiamenti inattesi. Usa un tag specifico come dpage/pgadmin4:9.13 così ogni membro del team esegue esattamente la stessa versione.

Precarica le connessioni ai server con servers.json

Se tutto il team condivide lo stesso setup Compose, non far registrare a tutti il server PostgreSQL dopo l’avvio dello stack. pgAdmin supporta un file servers.json che precompila le connessioni all’avvio. Montalo nel container così:

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

Ecco com’è un servers.json minimale:

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

Il server comparirà all’avvio di pgAdmin — nessuna configurazione manuale richiesta.

Conclusione

In questo articolo ti ho mostrato come configurare da zero pgAdmin 4 in Docker. Hai scritto un file Docker Compose che avvia insieme PostgreSQL e pgAdmin 4, hai collegato i due container usando il DNS interno di Docker e hai usato le funzioni principali di pgAdmin — Query Tool, browser dello schema e flusso di backup/ripristino.

Il principio chiave qui è la riproducibilità. 

Un file docker-compose.yml, un servers.json e un file .env sono tutto ciò che ti serve per consegnare a un collega un ambiente database completamente configurato. Così il problema del “sul mio computer funziona” non si presenterà più.

Per approfondire Docker e la containerizzazione, dai un’occhiata al nostro corso Intermediate Docker. È ricco di consigli utili su multi-stage build, networking e un approfondimento su Compose.