Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il database nell'API1. Perché un databasep. 12

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.

LeggiVuol direCosa fai
psycopg.OperationalError: connection is bad: connection to server on socket "/tmp/…/.s.PGSQL.5432" failed: No such file or directoryPython cerca PostgreSQL in un posto dove non c'è: o PostgreSQL è spento, o sta in un'altra cartellaPrima 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 refusedSta cercando PostgreSQL su una porta di rete e non c'è nessuno che rispondeUna 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 existPostgreSQL c'è, ma il database con quel nome no: nome scritto male, o non l'hai mai creatoControlla il nome nel codice e nel comando (createdb nome). Per l'elenco dei database: psql -l
psycopg.errors.UndefinedTable: relation "carrozze" does not existIl database c'è, ma dentro non c'è la tabella: non hai caricato il file .sql, o l'hai caricato in un altro databasepsql -d nome_database -f file.sql, poi psql -d nome_database -c "\dt" per vedere le tabelle
bash: fastapi: command not foundIl venv non è acceso in questo terminalesource .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ì dentropip install "psycopg[binary]", con il venv acceso
ERROR: [Errno 48] Address already in useUn 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 refused

E 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 Error

Nel 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:

  1. PostgreSQL: psql -d db_perche_un_database -c "SELECT 1". Se risponde, il database funziona.
  2. I dati: psql -d db_perche_un_database -c "SELECT * FROM treni". Se risponde con le righe, tabella e database sono a posto.
  3. 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).