Perché un database, se qualcosa va storto
Sette errori, sette uscite
Gli errori che vedrai di più quando l'API parla con PostgreSQL. Per ognuno: cosa leggi, cosa vuol dire, cosa fai.
La regola è quella del capitolo: una richiesta passa da client, API, psycopg e PostgreSQL. L'errore ti dice a quale pezzo ci siamo fermati. Quando è un 500, la risposta di curl non dice niente (solo Internal Server Error): la spiegazione sta nel terminale del server, nell'ultima riga del traceback. Come si legge: Leggere un traceback.
| Leggi | Vuol dire | Cosa fai |
|---|---|---|
psycopg.OperationalError: connection is bad: connection to server on socket "/tmp/…/.s.PGSQL.5432" failed: No such file or directory | Python cerca PostgreSQL in un posto dove non c'è: o PostgreSQL è spento, o sta in un'altra cartella | Prima controlla che sia acceso: su Mac brew services start postgresql@16, su Ubuntu sudo service postgresql start (va rifatto a ogni riaccensione del computer). Se è acceso, dì a psycopg dove cercarlo: Mac export PGHOST=/tmp, Ubuntu export PGHOST=/var/run/postgresql |
psycopg.OperationalError: connection failed: … port 5999 failed: … Connection refused | Sta cercando PostgreSQL su una porta di rete e non c'è nessuno che risponde | Una variabile d'ambiente (PGHOST o PGPORT) punta altrove. Guardala con echo $PGHOST $PGPORT: se hai valori che non hai scelto, unset PGHOST PGPORT |
FATAL: database "db_che_non_esiste" does not exist | PostgreSQL c'è, ma il database con quel nome no: nome scritto male, o non l'hai mai creato | Controlla il nome nel codice e nel comando (createdb nome). Per l'elenco dei database: psql -l |
psycopg.errors.UndefinedTable: relation "carrozze" does not exist | Il database c'è, ma dentro non c'è la tabella: non hai caricato il file .sql, o l'hai caricato in un altro database | psql -d nome_database -f file.sql, poi psql -d nome_database -c "\dt" per vedere le tabelle |
bash: fastapi: command not found | Il venv non è acceso in questo terminale | source .venv/bin/activate dalla cartella del progetto, e riprova. Succede spesso: pytest non parte, o non trova niente vale anche qui |
ModuleNotFoundError: No module named 'psycopg' | Il venv è acceso (o no) e psycopg non è stato installato lì dentro | pip install "psycopg[binary]", con il venv acceso |
ERROR: [Errno 48] Address already in use | Un altro server è già acceso sulla porta 8000 (spesso: quello di prima, che non hai fermato) | Trova il terminale e premi Ctrl+C. Se non lo trovi, accendi il nuovo su un'altra porta (su Ubuntu il numero tra parentesi è 98, il senso è lo stesso): fastapi dev centrale_database.py --port 8001 |
Come si vedono
Le prime due righe della tabella, come le scrive Python:
psycopg.OperationalError: connection is bad: connection to server on socket "/tmp/nessun-socket/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?psycopg.OperationalError: connection failed: connection to server at "127.0.0.1", port 5999 failed: could not receive data from server: Connection refusedE questo è ciò che vedi con curl quando il server FastAPI è acceso, ma il database no (qui il socket è sbagliato):
$ curl -i http://127.0.0.1:8000/treni/1
HTTP/1.1 500 Internal Server Error
date: Thu, 19 Nov 2026 17:58:47 GMT
server: uvicorn
content-length: 21
content-type: text/plain; charset=utf-8
Internal Server ErrorNel terminale del server, in fondo a un traceback lungo, c'è la riga che conta:
psycopg.OperationalError: connection is bad: connection to server on socket "/tmp/nessun-socket/.s.PGSQL.5432" failed: No such file or directory
Is the server running locally and accepting connections on that socket?Le altre due, quelle di psql:
$ psql -d db_che_non_esiste
psql: errore: connection to server on socket "/tmp/.s.PGSQL.5432" failed: FATAL: database "db_che_non_esiste" does not exist
$ psql -d db_perche_un_database -c "SELECT * FROM carrozze"
ERROR: relation "carrozze" does not exist
RIGA 1: SELECT * FROM carrozze
^Se non sai quale pezzo è rotto
Prova i pezzi uno alla volta, da quello in fondo:
- PostgreSQL:
psql -d db_perche_un_database -c "SELECT 1". Se risponde, il database funziona. - I dati:
psql -d db_perche_un_database -c "SELECT * FROM treni". Se risponde con le righe, tabella e database sono a posto. - L'API:
curl http://127.0.0.1:8000/treni. Se dà500, il problema è tra l'API e il database: leggi il terminale del server.
Così sai in due minuti se il guaio è nel database, nei dati o nel codice dell'API.
Gli errori che non danno errori
Uno solo, ed è quello di questo capitolo: il dato che sparisce. Se dopo un riavvio i treni nuovi non ci sono più, probabilmente stai ancora usando un dizionario (centrale_dizionario.py) al posto del database. Controlla quale file hai acceso: lo dice la prima riga del terminale del server, Using import string: centrale_database:app.
Per le altre pagine che aiutano: il Pronto soccorso ha le uscite per i problemi di ambiente (venv, terminale, PostgreSQL).