Home Assistant database recorder tuning guide

Keep the sensors you need for energy statistics recorded, then choose how much detailed history to retain. Reducing purge_keep_days and excluding a sensor have different consequences. This is a research guide based on Home Assistant’s documentation.

A normal time-based purge removes older detailed history and short-term statistics, while retaining long-term statistics. Excluding an entity can prevent the statistics you still need from being recorded. Decide which data matters before changing either setting.

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 - the volume recorded depends on which entities Recorder includes and how often they update.

A larger history database also adds data to backups that include it. Review retention and filters against the history and statistics you need before changing them. Reducing unwanted recording can limit growth, but database size alone does not identify the cause of slow performance.

The recorder options that 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 buffered changes are committed to the database (default 5 seconds). A longer interval reduces disk I/O and delays database writes; Home Assistant streams changes to the History and Activity panels immediately.
• include / exclude - limit what gets recorded, by domains, entities, or entity_globs. exclude also accepts event_types; there is no filter for a whole integration.
• 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 limits which entities are recorded, but it does not guarantee a small database; volume still depends on their updates and retention. Entities outside the allowlist are not recorded.

Can I shorten history without losing energy statistics?

Yes, if the energy sensors stay recorded. purge_keep_days controls detailed-history retention, with a default of 10 days. Home Assistant also creates five-minute short-term statistics and hourly long-term statistics for eligible sensors. The five-minute records follow Recorder retention; the hourly statistics survive that routine purge. Home Assistant’s statistics documentation explains the distinction.

That does not preserve every original reading. If a temperature graph changes from detailed points to hourly summaries after the retention window, it may be showing the expected change in data source, rather than missing statistics. Check the History panel or a Statistics graph card before increasing retention just to see older trends. Full-resolution history needs a longer retention window; changing the setting cannot recreate samples already purged.

Keep your Energy dashboard source entities out of Recorder’s exclude rules. Exclusion is not a way to keep only their hourly statistics. If a sensor disappears from statistics choices after a filter change, check that filter first: Home Assistant’s missing-statistics guidance specifically calls out excluded entities. include rules also deserve attention because entities outside an allowlist may no longer be recorded.

This applies to sensors eligible for statistics, not every entity in the house. The documented sensor state_class values are measurement, total and total_increasing. Do not assume a door-opening timeline will survive merely because energy totals do.

Moving off SQLite

SQLite is Home Assistant’s recommended database. Changing db_url to MariaDB or PostgreSQL is a separate migration decision, not a prerequisite for shorter retention. Home Assistant warns that changing databases can lose existing history and that migrating recorded data is not supported. Read the Recorder database guidance before switching. The app and container comparison covers deployment differences.

When the database is already huge

First choose how many days of detailed history you are willing to lose. The recorder.purge action deletes older events and state changes using keep_days; it is not lossless cleanup. Keep a recoverable backup before removing data you may need.

Purging does not necessarily make the database file smaller immediately. repack: true rebuilds it to reclaim space, but this is a heavy operation that can cause slowdowns and temporarily use more disk space. Home Assistant requires free temporary space at least equal to the database’s size for rebuilds and repacks. Check available disk space before starting.

Deleting home-assistant_v2.db also discards the long-term statistics stored in it. I would not use that as a routine performance fix. A fresh database does not establish why the old one grew or why Home Assistant was slow.