SYSADMIN JOURNAL / Linux · Networking · Security · HostingProcedure, appunti e soluzioni tecniche
Mysql

SQLite WAL: risolvere database is locked e checkpoint bloccati

Pubblicato il 18/11/2026

Il problema

Il database SQLite è in modalità WAL, ma una dashboard e diversi worker leggono e scrivono contemporaneamente. Un semplice timeout non sempre risolve: possono esserci transazioni lunghe e checkpoint che non avanzano.

Procedura di diagnostica

Si parte dai controlli non distruttivi, si identificano i processi o i servizi responsabili e soltanto dopo si interviene sulla configurazione. I percorsi e gli host riportati sono esempi da adattare al proprio ambiente.

sqlite3 /opt/app/data/app.db 'PRAGMA journal_mode; PRAGMA busy_timeout; PRAGMA wal_checkpoint(PASSIVE);'
lsof /opt/app/data/app.db /opt/app/data/app.db-wal /opt/app/data/app.db-shm
ps -eo pid,etime,cmd | grep -E 'worker|sqlite|app'

Interpretazione e soluzione

Verifica prima backup e processi in esecuzione. PRAGMA busy_timeout si imposta per ogni connessione, non una sola volta nel database. Con WAL c'è un solo writer alla volta: mantieni brevi le transazioni, serializza le scritture o implementa una coda. Non eliminare file -wal e -shm mentre i processi li usano. Esegui i checkpoint TRUNCATE soltanto in una finestra controllata, dopo aver verificato i reader attivi.

Checklist prima del rilascio

  • Backup dei file interessati e verifica dello stato iniziale.
  • Test del caso che ha generato l’errore, con log e timestamp verificabili.
  • Applicazione graduale della modifica, controllo sintattico dove previsto e verifica dopo il riavvio.
  • Rollback rapido se compare una regressione o un falso positivo.

Approfondimenti: GeoIP su Apache e debug redirect Apache.