Home Assistant database recorder tuning guide

The default Home Assistant recorder setup will quietly eat your storage alive. Out of the box, it keeps everything forever—every state change, every attribute update, every sensor reading. On a busy system, that’s gigabytes per week. This guide gets you to a sane configuration in about 30 minutes.

Why the default setup hurts

Home Assistant writes to a SQLite database. Every entity state change creates a row. If you have 50 temperature sensors updating every 60 seconds, that’s 72,000 rows per day just for temperatures. Add motion sensors, energy monitors, presence detectors, and device trackers, and you’re looking at hundreds of thousands of writes daily.

The consequences show up fast: UI becomes sluggish, backups bloat, and SQLite lock contention spikes during heavy automation runs. The database file grows until you either delete it or your storage fills up.

The fix isn’t complicated, but it requires actually configuring the recorder—you can’t just tweak it from the UI.

Practical configuration steps

The recorder integration has three settings that matter: what to include, how long to keep it, and how to purge.

Exclude what you don’t need. Most people should exclude the following:

• Logbook (handled separately)
• Events (unless you explicitly need them)
• Entity IDs with high-frequency updates like sensor.utility_meter_* or any energy tracking that samples every few seconds

Most device trackers update on every home/away transition—that’s fine to keep. But that one sensor that reports every 30 seconds for no reason? Exclude it.

recorder:
  purge_keep_days: 30
  exclude:
    domains:
      - scene
      - script
    entities:
      - sensor.utility_power
      - sensor.energy_consumption_total

This is a starting point. The right number of purge_keep_days depends on what you actually look back at. Most people need 7-14 days for troubleshooting. If you’re using the energy dashboard, 30 days is reasonable.

Debounce rapid state changes. Some entities flip state constantly—think of a motion sensor that toggles every few seconds in a busy room. Use the debounce option to collapse those into single writes:

sensor:
  - platform: template
    sensors:
      motion_hallway:
        ...
        debounce: 5

This stops a motion sensor from generating 50 database entries in a minute when you just care that motion happened.

Consider the database engine. SQLite works fine for most setups under 500 entities. If you’re running thousands of entities or want better write performance, consider moving to MariaDB or PostgreSQL. But that’s extra infrastructure work—start with getting SQLite tuned first.

Automation and long-term tradeoffs

One common mistake: keeping everything because “maybe I’ll need it later.” You won’t. In 99% of cases, you’re looking at the last few days for debugging. History beyond 30 days is mostly unused space.

The exception is energy monitoring. The energy dashboard needs 30+ days of data to show monthly usage trends. Keep more history if you’re serious about energy tracking, but consider using the dedicated Statistics integration instead of raw state storage—it stores summarized data much more efficiently.

For automation-heavy homes with motion sensors, contact sensors, and binary sensors firing constantly, focus on excluding those high-frequency entities. Keep thermostats, switches, and the few sensors you actually reference in dashboards.

When things go sideways

If your database is already huge, you need to purge it. The easiest approach: stop Home Assistant, delete home-assistant_v2.db, restart. You lose all history, but the system becomes responsive again.

A less destructive option: manually run the purge service from Developer Tools with keep_days set to 7. It’ll delete old data in chunks and won’t lock you out of your UI.

For ongoing maintenance, consider adding an automation that runs the purge service weekly. Most systems don’t need a running cron job—the built-in auto-purge handles it fine.

If your system crashes during a purge, that’s usually a sign the database is severely fragmented. Rebuild it by exporting via the SQLite CLI, then importing after recreating the database. It’s not fun, so set your purge settings correctly the first time.

Bottom line

Set purge_keep_days to 14-30, exclude high-frequency sensors you don’t use, and let the built-in purge do its job. Check your database size monthly—if it’s growing past 500MB on SQLite, tighten your exclusions. You don’t need more than a week of detailed history for practical troubleshooting, and the energy dashboard has its own storage path anyway.