Database Home Assistant Core: Errore SQLite database is locked e disk I/O error

A cosa serve questa guida

Home Assistant salva lo storico di stati e sensori in un file SQLite, home-assistant_v2.db. Uno spegnimento improvviso durante una scrittura, o una microSD lenta e usurata, possono lasciarlo bloccato (database is locked) o danneggiato (disk I/O error, database disk image is malformed).

Questa guida mette al sicuro il file, controlla se è danneggiato, lo ricostruisce con sqlite3 e riduce il carico futuro, così l'errore non si ripresenta.

Cosa ti serve per continuare

• Home Assistant OS con l'app Terminal & SSH. Se non l'hai: Impostazioni → Applicazioni → Installa app, cerca Terminal & SSH, premi Installa e poi Avvia.
• Spazio libero sul disco almeno pari a due volte la dimensione del database: lo controlli in Impostazioni → Sistema → Archiviazione.

Fase 1: Collegati via SSH, ferma Home Assistant e copia il database

Il motore di Home Assistant va fermato, altrimenti il file resta aperto. Il terminale web dell'app passa però dall'interfaccia di Home Assistant e si chiude appena il motore si ferma: per questo ci si collega con un client SSH dal computer.

1. Apri Impostazioni → Applicazioni → Terminal & SSH, scheda Configurazione: nel campo password scrivi una password temporanea robusta, nel campo apks aggiungi sqlite, nella sezione Rete imposta la porta 22, poi premi Salva e riavvia l'app.
2. Dal computer apri il terminale (su Windows: PowerShell) e digita ssh root@homeassistant.local, oppure ssh root@ seguito dall'IP del server; accetta la chiave alla prima connessione e inserisci la password.
3. Digita ha core stop e attendi il messaggio Command completed successfully: la sessione SSH resta attiva anche a motore fermo.
4. Digita cd /config e poi ls -lh home-assistant_v2.db*: vedi il database ed eventuali file -wal e -shm. Copiali tutti con mkdir -p /share/db-copia && cp home-assistant_v2.db* /share/db-copia/.

Fase 2: Controlla e ricostruisci il database

Lo strumento sqlite3 non è incluso di serie nell'app: l'opzione apks impostata al passaggio precedente lo installa a ogni avvio. Verifica che ci sia con sqlite3 --version.

1. Esegui sqlite3 home-assistant_v2.db "PRAGMA integrity_check;". Se la risposta è ok, il file è integro: salta alla Fase 3 e riavvia con ha core start.
2. Se compaiono errori, crea un file ricostruito con sqlite3 home-assistant_v2.db ".recover" | sqlite3 home-assistant_v2_fix.db e attendi il ritorno del prompt (con database grandi servono minuti).
3. Sposta da parte l'originale con mv home-assistant_v2.db home-assistant_v2.db.vecchio, elimina i file temporanei con rm -f home-assistant_v2.db-wal home-assistant_v2.db-shm e rendi attivo quello ricostruito con mv home-assistant_v2_fix.db home-assistant_v2.db.
4. Riavvia con ha core start e attendi qualche minuto prima di aprire l'interfaccia. A lavoro finito cancella la password dalla configurazione dell'app e svuota il campo della porta, così l'accesso SSH dalla rete torna disattivato.

Se la ricostruzione fallisce, puoi anche solo spostare da parte il file danneggiato: al riavvio Home Assistant crea un database nuovo e vuoto. Perdi lo storico, non la configurazione.

Fase 3: Riduci il carico sul database

Il Recorder (il componente che scrive lo storico) conserva 10 giorni di dati per ogni entità. Con molti sensori che cambiano spesso il file cresce in fretta e la scheda di memoria lavora di continuo.

1. Apri Impostazioni → Strumenti → Azioni e cerca l'azione recorder.purge (mostrata come "Purge Recorder database").
2. Imposta i giorni da conservare (es. 7), attiva l'opzione Riorganizza e premi Esegui azione. Senza "Riorganizza" i dati vecchi vengono eliminati ma il file non si riduce su disco.
3. Per rendere la modifica permanente ed escludere le entità più "rumorose", aggiungi la configurazione YAML qui sotto e riavvia.

Opzionale — YAML per Home Assistant

Questa configurazione vale solo per Home Assistant: aprila con l'app File editor, incollala in fondo a configuration.yaml (se esiste già un blocco recorder:, unisci le righe), poi controlla la configurazione e riavvia.

recorder:
  purge_keep_days: 7
  commit_interval: 30
  exclude:
    entity_globs:
      - sensor.*_uptime
      - sensor.*_linkquality
      - sensor.*_rssi

commit_interval: 30 raggruppa le scritture ogni 30 secondi invece di 5: meno usura del disco, al prezzo di uno storico che compare con qualche secondo di ritardo. Adatta i nomi in entity_globs ai sensori che hai davvero.

Verifica e test operativo

• Apri Impostazioni → Sistema → Registri e cerca "recorder".
• Apri Storico dalla barra laterale, scegli un sensore e controlla che i dati arrivino fino all'ora attuale.
• Dopo qualche giorno, in Impostazioni → Sistema → Riparazioni → menu a tre puntini → Informazioni di sistema, verifica che la dimensione stimata del database nella sezione Recorder resti stabile.

Cosa fare se qualcosa non funziona

Requisiti e risorse ufficiali

• Home Assistant: integrazione Recorder
• Home Assistant: modificare configuration.yaml
• App Terminal & SSH: documentazione

Se il file si corrompe spesso, la causa più comune è una microSD non adatta a scritture continue: un kit come il db-tronic Raspberry Pi 5 Kit va abbinato a un SSD, non solo alla scheda inclusa. In qualità di Affiliato Amazon ricevo un guadagno dagli acquisti idonei.

Verifica su Home Assistant 2026.9: 2 ottobre 2026.