Errori tipici durante l'installazione e la configurazione di PostgreSQL

1. Componenti principali di PostgreSQL

L'installer ti deve mettere su tre cose fondamentali: il server e due client. Ora ti spiego al volo cosa sono.

Server postgres

Questo è il cuore di PostgreSQL. Il server si occupa di:

• Gestire le richieste dei client.
• Gestire i dati: lettura, scrittura, aggiornamento.
• Garantire sicurezza e integrità dei dati.

Quando avvii il server PostgreSQL, lui è pronto a ricevere richieste dai client.

Client

I client sono programmi che si collegano al server e gli mandano query SQL. In PostgreSQL ci sono alcuni client molto usati:

• Programma psql: riga di comando per lavorare con PostgreSQL. Perfetto per chi è "vecchia scuola" o ama il terminale.
• Programma pgAdmin: interfaccia grafica per gestire il server. Tipo un coltellino svizzero per i database — bello e pratico.
• Altri client: in realtà ci sono decine di librerie e tool per lavorare con PostgreSQL da altri linguaggi, tipo psycopg3 per Python o pg per Ruby.

Come funzionano insieme questi componenti? L’utente fa una richiesta tramite il client (psql/pgAdmin) → il client manda la query al server postgres → il server elabora la richiesta usando i dati dal filesystem e dalla sua memoria → il risultato torna al client.

2. Collegarsi al database dal terminale

Come spero ti ricordi, psql è il programma per lavorare con PostgreSQL dalla riga di comando. È perfetto se vuoi controllare qualcosa al volo, fare una query o esplorare il database.

Esempio: usare psql

# Ci colleghiamo al server
psql -U postgres

Se tutto va bene, vedrai una schermata tipo questa:

psql (17.5)
Type "help" for help.

postgres=#

Congratulazioni, sei nella shell di psql!

Una volta collegato, puoi lanciare i comandi:

-- Crea un database
CREATE DATABASE test_db;

-- Vedi la lista dei database
\l

-- Passa a un database specifico
\c test_db

-- Esci dalla sessione
\q

È uno strumento top per chi ama lavorare "direttamente".

3. Problemi comuni con l’installazione

E se qualcosa va storto? Se non vedi la lista dei database, o non riesci nemmeno a fare il login? L’installer finisce e basta 😡 Errori, insulti nel terminale, postgres non parte, psql fa finta di non conoscerti. Ti suona familiare? Congratulazioni — sei nella classica fase «ho fatto tutto giusto, ma non funziona niente». 😅

Vediamo insieme le trappole più comuni in cui inciampa ogni secondo principiante. E facciamolo con la testa fredda, una tazza di tè caldo e la voglia di sconfiggere qualsiasi errore nei log. Quindi armati di pazienza — oggi mettiamo ordine e liberiamo PostgreSQL dalla sindrome «funziona solo al mentor». 🛠️🐘

Problema 1. Conflitto di porte

Forse il caso più diffuso. Di default PostgreSQL usa la porta 5432 per collegarsi al server. Se questa porta è già occupata da un’altra app, l’installazione va liscia, ma il server non parte.

Come riconoscere il problema?

Quando avvii PostgreSQL il server si rifiuta di partire, oppure mostra un messaggio tipo:

could not bind IPv4 socket: Address already in use

Soluzione:

Controlla quale app sta usando la porta 5432. Su Linux puoi farlo con:

sudo netstat -tuln | grep 5432

Su Windows nella console esegui:

netstat -ano | find "5432"

Se la porta è davvero occupata, puoi cambiare la porta di PostgreSQL. Apri il file postgresql.conf (si trova nella cartella dati di PostgreSQL) e cerca la riga:

#port = 5432

Cambia la porta con una libera, tipo:

port = 5433

Non dimenticare di riavviare il server dopo la modifica.

Problema 2. Permessi insufficienti

Su Windows può capitare che l’installer di PostgreSQL non riesca a finire l’installazione perché l’utente attuale non ha abbastanza permessi.

Come riconoscere il problema?

L’installer si blocca o mostra un messaggio che mancano i permessi.

Soluzione:

Avvia l’installazione come amministratore. Clicca col destro sull’installer e scegli "Esegui come amministratore".

Problema 3. Problemi con le variabili d’ambiente

A volte, dopo aver installato PostgreSQL, il comando psql non viene riconosciuto nel terminale.

Come riconoscere il problema?

Quando provi a lanciare psql vedi un messaggio tipo:

'psql' is not recognized as an internal or external command

Soluzione:

Questo errore succede perché il percorso alla cartella dei binari di PostgreSQL (tipo C:\Program Files\PostgreSQL\17\bin) non è stato aggiunto alle variabili d’ambiente.

Per sistemare su Windows:

1. Apri "Proprietà del sistema" → "Avanzate" → "Variabili d’ambiente".
2. Cerca la variabile Path nella sezione "Variabili di sistema" e modificala.
3. Aggiungi il percorso della cartella bin di PostgreSQL. Tipo:

   
   C:\Program Files\PostgreSQL\17\bin
           

4. Dopo, riavvia il terminale.

4. Errori di connessione al server

A volte fila tutto liscio: avvii PostgreSQL, apri psql e ti colleghi al database senza problemi. Ma a volte... boom, errore. Qualcosa ti blocca. La password sembra giusta, il server sembra attivo... Ma psql ti sgrida.

Niente panico — questi errori capitano a tutti. Qui sotto vediamo i problemi di connessione più comuni e come risolverli al volo.

Problema 1. Password sbagliata per l’utente postgres

Quando installi PostgreSQL, imposti una password per il superuser del DBMS postgres. Se la password è stata dimenticata o inserita male, non puoi collegarti al server.

Come riconoscere il problema?

Quando lanci il comando di connessione:

psql -U postgres

Ottieni un errore tipo:

password authentication failed for user "postgres"

Soluzione:

Se hai dimenticato la password di postgres, puoi reimpostarla così:

1. Apri il file pg_hba.conf, che si trova nella cartella dati di PostgreSQL C:\Program Files\PostgreSQL\17\data
2. Sostituisci la riga:

   
   host    all             all             127.0.0.1/32            md5
           

   Con:

   
   host    all             all             127.0.0.1/32            trust
           

   Così disattivi temporaneamente il controllo password.

3. Riavvia il server PostgreSQL.
4. Collegati al database senza password:

   
   psql -U postgres
           

5. Cambia la password con il comando:

   
   ALTER ROLE postgres PASSWORD 'new_password';
           

6. Rimetti pg_hba.conf come prima e riavvia il server.

Problema 2. Host o porta sbagliata

Se il client psql non riesce a collegarsi al server, controlla di aver messo host e porta giusti nelle impostazioni.

Come riconoscere il problema?

L’errore di connessione può essere tipo:

could not connect to server: Connection refused
    Is the server running on host "127.0.0.1" and accepting
    TCP/IP connections on port 5432?

Soluzione:

Controlla che il server PostgreSQL sia avviato:

systemctl status postgresql

(Linux) oppure apri "Servizi" su Windows (Ctrl+Shift+Esc).

Se il server è attivo, controlla le impostazioni in pg_hba.conf. Assicurati che le righe di connessione per localhost (127.0.0.1) e il tuo IP siano corrette. Tipo:

host    all             all             127.0.0.1/32            md5
host    all             all             192.168.1.100/32        md5

5. Consigli generali per risolvere i problemi

• Usa i log di PostgreSQL
  I log sono i tuoi migliori amici. Li trovi nella cartella dati di PostgreSQL (tipo /var/log/postgresql/ su Linux). Se qualcosa va storto, parti sempre dai log.
• Controlla la documentazione
  PostgreSQL ha una delle documentazioni migliori che ci siano. Se hai un errore, è molto probabile che la soluzione sia nella doc ufficiale: https://www.postgresql.org/docs/.
• Chiedi alla community
  Se sei bloccato, dai un’occhiata su Stack Overflow, ChatGPT o sui forum di PostgreSQL. Le probabilità di trovare una soluzione pronta sono alte.

P.S.

Importante! Se proprio non riesci a farlo funzionare - scrivici al supporto: ti aiutiamo a risolvere il problema e poi aggiorniamo anche questo articolo.