Home Assistant database recorder tuning guide

The default Home Assistant recorder keeps a lot of history, and on a busy system the database grows fast — every state change and attribute update becomes a row. The good news: the recorder is easy to tune, and a sensible config takes about 30 minutes. This guide sticks to options that actually exist in Home Assistant.

Why the default setup grows

By default the recorder keeps 10 days of history in a SQLite database (home-assistant_v2.db in your config folder). Every entity state change writes a row. With dozens of frequently-updating sensors — a whole-home energy meter like the Shelly Pro 3EM, a zone-tracking presence sensor like the Aqara FP2, motion sensors, device trackers — that’s easily hundreds of thousands of rows a day.

The symptoms: a sluggish History/Logbook UI, bloated backups, and a database file that keeps climbing. The fix is to record less, not to keep everything and hope.

The recorder options that actually exist

You configure the recorder in configuration.yaml. The real, documented options include:

• purge_keep_days — how many days of history to keep (default 10).
• auto_purge — whether the nightly purge runs automatically (default true, at ~04:12 local time).
• commit_interval — how often, in seconds, buffered changes are written to disk (default 5). Raising it reduces disk I/O at the cost of slightly staler history.
• include / exclude — limit what gets recorded, by domains, entities, entity_globs, or whole integrations.
• db_url — point the recorder at an external database such as MariaDB or PostgreSQL.

There is no debounce option on the recorder, and the recorder does not change how often a sensor updates — it only controls what’s written and how often it’s flushed. To reduce how often a sensor itself reports, you adjust that on the integration or device (for example a polling integration’s scan interval, or a Zigbee2MQTT/template reporting setting), not in the recorder.

A practical starting configuration

The cleanest approach for most homes is to record only what you’ll actually look at, using exclude to drop noisy domains and entities you never reference:

recorder:
  purge_keep_days: 14
  exclude:
    domains:
      - automation
      - update
    entity_globs:
      - sensor.*_uptime
      - sensor.*_last_seen
    entities:
      - sensor.time
      - sensor.date

Fourteen days is a reasonable default for troubleshooting. If you mostly debug recent issues, 7 is fine; if you lean on long history, raise it — but remember the energy dashboard’s long-term data is stored separately (see below), so you don’t need a huge purge_keep_days just for energy charts.

If you prefer the opposite philosophy, use include to record only a hand-picked set of entities and let everything else go unrecorded. That keeps the database tiny but means new entities aren’t logged until you add them.

Long-term statistics are separate

Home Assistant keeps long-term statistics (hourly min/max/mean and metered totals) in the same database but on a separate, compact track that is not removed by purge_keep_days. This is what powers the energy dashboard and long-range history graphs for sensors that have a state_class. So you can keep purge_keep_days short for detailed history while still seeing months of energy and statistics trends.

For even longer or external retention/graphing, many people send data to InfluxDB (via the InfluxDB integration) and visualize it in Grafana, leaving the recorder lean.

Moving off SQLite

SQLite is fine for most setups. If you have a very large entity count or want better write performance, point db_url at MariaDB or PostgreSQL (commonly run as an add-on or separate container). It’s extra infrastructure, so tune SQLite first and only migrate if you actually hit its limits — and if the real bottleneck is the machine rather than the database, a faster host helps more than a database swap (see the best mini PCs for Home Assistant).

When the database is already huge

• Purge in place (non-destructive): call the recorder.purge action from Developer Tools → Actions with keep_days set low and repack: true. repack rebuilds the file to actually reclaim space (important on SQLite, where deleting rows alone doesn’t shrink the file).
• Nuclear option: stop Home Assistant, delete home-assistant_v2.db, restart. You lose all history (including long-term statistics), but you get an instantly responsive system. Use only as a last resort.

Bottom line

Set purge_keep_days to 7–14, exclude noisy domains and entity globs you never look at, and let auto_purge do its nightly job. Leave long-term statistics alone — they’re compact and power your energy and history trends regardless of purge_keep_days. A leaner database also makes backups faster and smaller. There’s no debounce setting; control report frequency at the source, and reach for MariaDB/PostgreSQL only if SQLite can’t keep up.