Recorder Home Assistant: come ridurre un database troppo grande

Introduzione

Home Assistant rallenta? Il database home-assistant_v2.db ha superato il GB? Gli aggiornamenti richiedono minuti? La soluzione non è avere più spazio, ma capire cosa il recorder sta scrivendo dentro quel file, e per quanto tempo lo conserva.

Questo articolo analizza nel dettaglio questo componente per mantenere la tua istanza sempre ottimizzata — ed è il primo di una serie che dedicheremo alla manutenzione ordinaria e straordinaria di Home Assistant.

Cos’è il recorder e perché il database cresce

Ma cos’è il recorder? L’integrazione memorizza la cronologia delle entità: ogni cambio di stato e ogni azione. Ogni volta che un’entità cambia stato — per esempio una luce che passa da off a on — viene generato un evento state_changed, che il recorder scrive nel database home-assistant_v2.db. Da lì attingono tutte le altre funzioni: history, grafici, statistiche, logbook (Activity).

Lo stesso flusso in movimento: ogni evento diventa una riga nel database

Qui sotto trovi la schermata Activity, che legge proprio dal recorder per mostrare i dati: in questo caso, abbiamo appena acceso una luce. Se la timeline delle attività ti è ancora poco familiare, ne ho parlato in dettaglio nell’articolo sul Registro Attività di Home Assistant.

Altri database supportati

Home Assistant usa come database di default SQLite, con il nome home-assistant_v2.db, ma è possibile usare altre soluzioni. I database supportati sono:

• MariaDB ≥ 10.3
• MySQL ≥ 8.0
• PostgreSQL ≥ 12
• SQLite ≥ 3.40.1

Tutti i dettagli sui motori supportati e sulle stringhe di connessione sono nella documentazione ufficiale del recorder.

Statistiche a breve e lungo termine

Una distinzione importante — la tabella qui sotto aiuta a visualizzarla — è che esistono due modi diversi di registrare i dati, in base al tipo di entità. In breve, ed è un argomento ancora dibattuto nella community: i sensori numerici (per esempio la temperatura) generano statistiche a lungo termine, che sopravvivono come aggregati (medie orarie). Gli interruttori (una luce che passa da off a on) generano invece solo statistiche a breve termine, cancellate dal purge dopo 10 giorni di default (valore modificabile).

Per riassumere: un consumo energetico ti mostrerà grafici anche a distanza di 6 mesi, una luce accesa o spenta no. Il meccanismo degli aggregati orari è descritto nella documentazione ufficiale delle statistiche.

Nota importante. Un limite noto di Home Assistant, discusso attivamente dalla community e ancora, a quanto pare, senza soluzione: la issue #137602 su GitHub chiede esattamente questo — statistiche a lungo termine anche per i sensori binari. Se ti serve tenere traccia di quando si accende una luce per più di 10 giorni, l’unica strada è alzare purge_keep_days (a costo di un database più pesante) o affidarti a un database esterno.

Diagnosticare cosa riempie il database

Il primo controllo, veloce, è la dimensione stimata del database: Impostazioni → Sistema → Repairs → menu (⋮) → System information. Nel mio caso, con la configurazione che vedi più sotto, il database pesa 47,11 MiB — piccolo, perché tengo purge_keep_days basso ed escludo parecchio.

Per capire quali entità pesano di più, serve interrogare direttamente il database. C’è un add-on che puoi installare comodamente da Impostazioni → App → installa app e cerca “SQLite Web”. Il repository e la documentazione sono su GitHub: app-sqlite-web e la sua documentazione.

Da qui puoi eseguire query dirette sul database. Questa è la query che ho usato per trovare le 10 entità che scrivono di più:

SELECT COUNT(*) AS cnt,
     COUNT(*) * 100 / (SELECT COUNT(*) FROM states) AS cnt_pct,
     states_meta.entity_id
FROM states
INNER JOIN states_meta ON states.metadata_id = states_meta.metadata_id
GROUP BY states_meta.entity_id
ORDER BY cnt DESC
LIMIT 10;

Per la mia configurazione, questo il risultato.

Al primo posto, col 20-21% delle righe: sensor.0xa4c138e9e1c7c89d_illuminance — è il mio radar WZ-M100. Il sensore di illuminamento scrive così spesso perché aggiorna il valore in continuo, non solo agli eventi di presenza: è il dispositivo che scrive di più sul mio database. Ne ho fatto una recensione completa del Wenzhi WZ-M100, se vuoi approfondire.

Al terzo e quinto posto: sensor.system_monitor_processor_temperature e sensor.system_monitor_processor_use — classico rumore dell’integrazione System Monitor, che polla ogni pochi secondi per natura sua. Vale la pena valutare se escluderli.

Voltage e current di tre dispositivi diversi — le mie prese smart Zigbee con misura consumi. Qui però attenzione prima di escluderle: dipende da dove sono montate. Tutte, potenzialmente, possono alimentare l’Energy Dashboard — e se lo fanno, escluderle interrompe silenziosamente le statistiche a lungo termine che il grafico usa. Prima di escludere per peso un’entità, controlla sempre se è collegata a una fonte della Dashboard Energia.

Le due leve principali: purge e exclude

purge_keep_days — di default 10 giorni. auto_purge gira ogni notte alle 04:12; auto_repack ogni secondo weekend, dopo il purge. Dal 2023.12 Home Assistant sconsiglia di alzare genericamente questo valore, perché le statistiche a lungo termine bastano per i grafici numerici — ma non per le entità booleane, come abbiamo visto sopra.

Io tengo purge_keep_days a 5 giorni, non 10, e non è una scelta recente: deriva da impostazioni ereditate nel tempo, perché ho sempre cercato di usare hardware leggero e a basso consumo — Raspberry Pi in testa — e di conseguenza di contenere cicli di scrittura e spazio occupato, sia con purge_keep_days sia con le esclusioni. Onestamente, con l’evoluzione dell’ecosistema e l’ottimizzazione di Home Assistant, tenerlo così stretto è sempre meno necessario — ma io preferisco il controllo totale, e per ora resta così. Mi riservo di alzarlo in futuro se serve.

C’è un caso in cui alzarlo diventa quasi obbligatorio: se usi la simulazione di presenza con il metodo nativo durante una vacanza più lunga di 10 giorni, il recorder ha già cancellato la history che la simulazione dovrebbe rileggere. In quel caso, per quei giorni serve alzare temporaneamente purge_keep_days.

Ecco la mia configurazione reale in configuration.yaml:

recorder:
auto_purge: true
purge_keep_days: 5
exclude:
  domains:
    - automation
    - update
    - binary_sensor
    - person
    - select
    - sun
    - tts
    - weather
    - zone
    - script
    - text
    - number
include:
  entities:
    - binary_sensor.0xa4c138e9e1c7c89d_presence
    - binary_sensor.0xa4c138dccb4cb231_contact

Escludo, attraverso exclude: domains, tutte le entità che non voglio tracciare: automazioni, update, meteo, tts, zone, script, helper testo e numero. Per la mia configurazione non mi servono, ma è ovvio che ognuno deve adattare questa lista alle proprie esigenze.

Attenzione a un dettaglio che confonde spesso: non esiste un dominio generico input. Gli helper creati dall’interfaccia vivono in domini separati — input_boolean, input_number, input_select, input_text, input_datetime — e se vuoi escluderli vanno elencati uno per uno.

Dei binary_sensor — quelli acceso/spento, per intenderci — escludo l’intero dominio ma tengo solo presenza e contatto del varco della porta, per avere sempre un riscontro di quando le porte sono state aperte. Funziona perché Home Assistant applica prima l’include: entities, che ha precedenza sull’exclude: domains: la storia di questo entity_id resta anche oltre i 10 giorni standard.

Quando usare exclude e quando include

SQLite è abbastanza, o serve MariaDB?

Ci sono alternative, come da documentazione ufficiale, per usare altri database — anche ospitati su server esterni, casalinghi o meno, su Docker eccetera. Non ne parliamo qui: è un lavoro aggiuntivo che merita un articolo a parte.

Nella mia configurazione uso il database ufficiale, SQLite. Funziona, e funziona abbastanza bene: non ho mai sentito la necessità di aggiungere un database esterno. Il consiglio è comunque quello di usare hardware appropriato: se usi un Raspberry Pi, valuta di passare a una SSD e non restare sulla SD card interna — le scritture continue del recorder tendono a rovinarla molto più in fretta. Per me è un passaggio obbligato: ne parlo nella guida a Home Assistant su SSD con Raspberry Pi.

Se invece il tuo obiettivo non è alleggerire il database ma estrarne dati storici da mostrare in dashboard, la strada giusta non è cambiare motore: sono i sensori SQL per i dati storici, che leggono dal database esistente senza appesantirlo ulteriormente.

recorder.purge_entities: pulizia mirata senza toccare tutto

A volte non serve toccare la configurazione globale: basta ripulire i dati di un’entità specifica. Il caso più comune è quando rinomini un dispositivo — l’entity_id vecchio resta nel database anche se non scrive più nulla di nuovo.

L’azione recorder.purge_entities risolve proprio questo: da Strumenti per sviluppatori → Azioni, cerca recorder.purge_entities e indica l’entity_id (o il pattern) da ripulire. A differenza del purge automatico, agisce subito e solo su quello che indichi — utile dopo una migrazione di dispositivi Zigbee, quando ti restano entità “fantasma” con il vecchio indirizzo IEEE.

Checklist finale e cosa NON fare

Questa è la configurazione minima da cui partire, con i valori commentati:

recorder:
auto_purge: true      # lascialo true: senza, serve un'automazione che chiami recorder.purge
purge_keep_days: 10   # 5 se, come me, vuoi tenere il database il più leggero possibile
commit_interval: 5    # alzalo (es. 30) se sei ancora su SD card
exclude:
  domains: []         # System Monitor, automation, update: buoni candidati
include:
  entities: []        # le eccezioni puntuali che vuoi salvare comunque

Cosa evitare:

• Non disattivare auto_purge senza sostituirlo con un’automazione che chiami recorder.purge — altrimenti il database cresce senza controllo.
• Non lasciare commit_interval al default su SD card: alzalo, la raccomandazione ufficiale è intorno ai 30 secondi.
• Non escludere per peso senza controllare prima l’Energy Dashboard — vedi sopra.

Un’ultima raccomandazione prima di mettere mano alla configurazione: fai un backup. Se non ne hai ancora uno automatico fuori dal Raspberry, la procedura è in backup di Home Assistant su cloud.

Conclusione

Il recorder non è un componente da configurare una volta e dimenticare: cresce con la tua installazione, e vale la pena controllarlo ogni tanto con la stessa query che hai visto qui. La mia configurazione è cambiata parecchio nel tempo: ho aggiunto ed eliminato voci più volte, seguendo le esigenze del momento e i dispositivi che entravano e uscivano dall’impianto.

Detto questo, va messo in chiaro: tutto questo ha senso solo se vuoi un controllo granulare anche su questo componente. Home Assistant funziona benissimo anche senza toccare il recorder. Il database può crescere parecchio, è vero, ma con il passare degli anni e delle release le cose sono nettamente migliorate.

Se stai muovendo i primi passi e vuoi capire meglio come sono organizzati i pezzi del sistema, parti da Home Assistant: cos’è e come funziona.

Se hai trovato sorprese nella tua classifica delle entità più pesanti, condividile taggando @wearesmartit sui social — sono curioso di vedere cosa scrive di più nel tuo database. Nel prossimo articolo della serie Manutenzione vedremo gli errori più comuni in Home Assistant e come diagnosticarli.