Files
Anubis/docs/adr/0015-postgresql-con-init-nei-container.md
Alby96andClaude Opus 5.5 74809068af
ci / test (postgres) (push) Successful in 3m13s
ci / test (sqlite) (push) Successful in 4m23s
ci / test (postgres) (pull_request) Successful in 3m41s
ci / test (sqlite) (pull_request) Successful in 4m28s
ci / image (push) Successful in 1m46s
ci / image (pull_request) Successful in 1m1s
Turn off disk syncs on the CI test PostgreSQL (refs #98)
With the restarts gone, a rerun still failed 7 tests on read timeouts. The
server log shows why: every DROP DATABASE of the tests forces an immediate
checkpoint, one at a time, and on the runner's disk the sync alone took up
to 37 seconds, so queued drops passed the client's 30-second timeout. The
service is a throwaway, so initdb now sets fsync, synchronous_commit and
full_page_writes off. docker-compose.yml and real databases keep them on.
ADR 0015 updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 15:27:48 +01:00

5.9 KiB

0015 — PostgreSQL nei container con un processo init; nella CI, senza sincronizzazioni su disco

Data: 2026-11-15 · Stato: accettata · Precisa la CI (SPEC 15.5, ADR 0007) e il docker-compose.yml di sviluppo, issue #98, senza componenti esterni nuovi

Contesto

Dal 14 novembre 2026 il lavoro test (postgres) della CI falliva spesso, ma non sempre. Dopo uno-cinque minuti di test, il PostgreSQL di servizio chiudeva tutte le connessioni. I test rimasti fallivano con 57P03: the database system is in recovery mode o con EndOfStreamException. Rilanciando il lavoro passava. In locale la suite passava sempre.

Il registro del lavoro non mostrava quello del server. Per vederlo, la CI ora stampa a fine lavoro registro, stato e memoria del contenitore PostgreSQL (tasks ci-service-log). Li legge dal socket di Docker che l'esecutore monta nel lavoro, senza il client docker né altro da installare.

In una prova con la suite ripetuta tre volte sullo stesso server, il server si è riavviato quattro volte. Ogni volta il registro dice la stessa cosa:

LOG:  untracked child process (PID 248) exited with exit code 2
LOG:  terminating any other active server processes
LOG:  all server processes terminated; reinitializing

Nessun processo ucciso per memoria (OOMKilled false, nessun evento oom di Docker) e nessun segnale. Il processo "sconosciuto" che esce con codice 2 è pg_isready. Il codice 2 vuol dire "il server non ha risposto".

Che cosa succede:

  1. Docker esegue il controllo di salute dentro il contenitore come /bin/sh -c "pg_isready …".
  2. Sull'esecutore di Unraid il disco è lento. Ogni DROP DATABASE dei test forza un checkpoint immediato, con fino a 21 secondi di scrittura sul disco. In quei momenti il server può metterci più di 3 secondi a rispondere.
  3. Passato il tempo massimo del controllo (--health-timeout 3s), Docker chiude la shell. pg_isready resta senza genitore e il sistema lo affida al processo 1 del contenitore. L'immagine postgres non ha un processo init, quindi il processo 1 è PostgreSQL stesso.
  4. Quando pg_isready si arrende ed esce, PostgreSQL vede morire un figlio che non conosce. Per prudenza lo tratta come un suo processo andato in crash: chiude tutte le connessioni e rifà il recupero dal registro delle scritture.

Spiega anche gli altri indizi:

  • capita solo a volte, perché serve un server lento proprio mentre scade il controllo;
  • si vede da quando la suite è cresciuta con il commit della raccolta dei dati (issue #95), cioè più database creati e cancellati;
  • in locale non capita, perché il disco è veloce.

Non c'entrano la memoria, /dev/shm (64 MiB, il server ne usa poco) e pg_database_size del campionatore. Il CREATE/DROP DATABASE dei test rende il server lento, ma da solo non lo fa ripartire.

Seconda causa, vista dopo la prima correzione. In un'esecuzione con la correzione il server non è più ripartito, ma 7 test sono falliti lo stesso:

  • Timeout during reading attempt dopo circa 1 minuto e 18 secondi;
  • /primo-avvio?errore=database nel test del primo avvio desktop, lo stesso errore visto il 14 novembre nell'esecuzione 304.

Il registro del server mostra il motivo:

  • ogni DROP DATABASE forza un checkpoint immediato, e i checkpoint passano uno alla volta;
  • sul disco dell'esecutore la sola sincronizzazione su disco ha richiesto fino a 37 secondi (sync=36.849 s);
  • i DROP DATABASE in coda hanno superato i 30 secondi di attesa del client (canceling statement due to user request);
  • il test desktop non ha avuto la connessione nei 5 secondi dell'applicazione.

Il server era vivo, ma fermo ad aspettare il disco.

Decisione

  1. Un processo init davanti a PostgreSQL. Il servizio postgres della CI parte con --init, e quello di docker-compose.yml con init: true. Il processo 1 diventa il piccolo init di Docker: raccoglie lui i processi rimasti senza genitore, e PostgreSQL non li vede più.
  2. pg_isready si arrende prima di Docker. Il controllo è pg_isready -U anubis -d anubis -t 5 con --health-timeout 15s. Così Docker non chiude mai la shell mentre pg_isready sta ancora aspettando. L'intervallo resta di 3 secondi, quindi l'avvio non rallenta.
  3. Nella CI il PostgreSQL dei test non sincronizza su disco. Il servizio nasce con POSTGRES_INITDB_ARGS: "--no-sync -c fsync=off -c synchronous_commit=off -c full_page_writes=off" (l'opzione -c di initdb esiste da PostgreSQL 16). Così il checkpoint forzato da ogni DROP DATABASE scrive solo nella memoria del sistema e dura millisecondi. È ammesso solo perché quel server vive per un lavoro e poi si butta. Non vale per docker-compose.yml né per nessun database vero: lì un'interruzione di corrente senza fsync può rovinare i dati.
  4. Il registro del server resta nella CI. Il passo PostgreSQL log gira sempre a fine lavoro test (postgres). Mostra anche se l'init è attivo e com'è il controllo di salute. Il prossimo problema del server si legge lì, senza rilanciare alla cieca.

Le misure 1 e 2 si coprono a vicenda: ognuna da sola basta a togliere la prima causa. La 3 toglie la seconda, e rende anche più raro un controllo di salute lento.

Conseguenze

  • Il lavoro test (postgres) non perde più il server a metà. Rilanciarlo per farlo passare nascondeva la causa, e ora non serve più.
  • Nessun test e nessuna parte di Anubis cambia: il difetto era nel modo in cui gira il contenitore, non nel bot.
  • I test su PostgreSQL nella CI non provano la durata dei dati dopo un'interruzione. Non lo facevano neanche prima: quella è una proprietà di PostgreSQL, non di Anubis.
  • Per l'installazione su Unraid: se il PostgreSQL che usa Anubis gira in un container con un controllo di salute basato su pg_isready e senza init, ha lo stesso rischio sotto carico. Il rimedio è lo stesso: l'opzione --init (in Unraid, "Extra Parameters") oppure un controllo con -t più breve del suo tempo massimo. Il template deploy/unraid/anubis.xml non installa PostgreSQL, quindi lì non cambia niente.