Your recorder database is too big — what to purge and what to exclude

Updated 25 September 2026

The symptom

Home Assistant has got slow. History graphs take ages to load, or time out. Backups are gigabytes. The disk is filling up, and on a Raspberry Pi with an SD card, things have started going wrong in ways that are hard to pin down. In the log you may see warnings that the recorder is falling behind.

The file behind all of this is usually home-assistant_v2.db in your config folder: the recorder database, where Home Assistant writes every state change of every entity so it can draw history graphs.

Why it happens

The recorder saves every change, and some entities change constantly. A power monitoring plug that reports every second, a Bluetooth tracker that updates signal strength every few seconds, a sensor with a dozen attributes that tick over each time: each one can write more rows than the rest of your house put together.

By default Home Assistant keeps ten days of detailed history and purges older rows every night. Two things break that:

A handful of very chatty entities make ten days far bigger than it should be.
The keep period was raised (people set 365 days to get long graphs), or the nightly purge was switched off.

Long-term statistics (the hourly averages behind energy and long history graphs) are kept separately and aren't removed by the purge, so shortening detailed history doesn't lose your energy dashboard.

Our check reads the recorder's own status and any database size sensor you have, and flags the database once it passes 2 GB or once the recorder's queue is more than half full. On a demonstration instance, where neither was true, it read:

What the check read from the recorder

recording: True
backlog: 0 of a 65000 maximum
database size sensors found: 0

Demonstration instance: a disposable Home Assistant with made-up entities, run on our own test bench. Not a customer's house. The text in the box is exactly what the service's check and safety rules produced on it.

How to fix it yourself

Take a backup, or at least check the disk has room. Purged history is gone for good. A backup protects you if you purge the wrong thing. Shrinking the file afterwards (a repack) also needs free space roughly the size of the database while it works.
Find out how big it actually is. On Home Assistant OS, Settings → System → Storage shows disk use. To track the database itself, add the File size integration pointed at /config/home-assistant_v2.db, or use the SQL integration's database size example.
Find the entities doing the damage. Install the SQLite Web app (previously called an add-on) on Home Assistant OS, or open a copy of the database with any SQLite tool elsewhere, and run:

SELECT states_meta.entity_id, COUNT(*) AS rows
FROM states
JOIN states_meta ON states.metadata_id = states_meta.metadata_id
GROUP BY states_meta.entity_id
ORDER BY rows DESC
LIMIT 20;

The top few entities are usually responsible for most of the file. Make a note of them.

Stop recording what you don't need. For each noisy entity, ask whether you've ever looked at its history. Signal strength, uptime, "last seen", per-second power readings you only ever look at as an hourly total: those can go. The recorder is configured in YAML (it has no settings page), so add an exclude to configuration.yaml. If you already have a recorder: section, add to it rather than starting a second one:

recorder:
  purge_keep_days: 10
  exclude:
    entity_globs:
      - sensor.*_signal_strength
      - sensor.*_uptime
    entities:
      - sensor.garage_plug_power

Check your configuration (Developer tools → YAML → Check configuration) and restart Home Assistant for it to take effect.

Purge what's already there. In Developer tools → Actions, run recorder.purge_entities for the noisy entities you just excluded, with keep_days: 0, to remove their history now rather than waiting. Then run recorder.purge with the number of days you actually want (ten is the default and plenty for most houses).
Shrink the file. Deleting rows doesn't make the file smaller by itself. Run recorder.purge once more with repack: true. Home Assistant will be slow while it runs; do it at a quiet time.
Check it stays fixed. Look at the file size again tomorrow, and in a week. It should grow a little and then level off as the nightly purge keeps pace.

When the database is on an SD card

A big, busy database on an SD card wears the card out, and a worn card is one of the most common ways a Home Assistant install dies. If you're on a Raspberry Pi booting from SD, moving to an SSD (or to a small PC) is the real fix, and trimming the database buys you time until then.

What about a different database?

You can point the recorder at MariaDB or PostgreSQL instead of the built-in SQLite. It helps on very large installs, but it doesn't fix a database that's big because of what's being recorded, and an external database isn't included in Home Assistant's own backups. Fix what's being recorded first.

Do it properly

Exclude at the source. Excluding a noisy entity from the recorder beats purging it every week.
Don't raise purge_keep_days to get long history. Long-term statistics already give you months of hourly data for anything with a unit, at a fraction of the size.
If you add or change YAML, add to the existing top-level recorder: block. A second recorder: block silently replaces the first.
The check this service applies before trimming history: only when the check reports the database as oversized or the recorder as falling behind; it always keeps between 7 and 30 days of history, never less; and because deleted history can't be recovered, it's never pre-ticked. On a healthy recorder it refuses:

The safety rule for trimming history, on that recorder

Trim history to 10 days -> REFUSED: the history database is not reported as oversized or behind, and deleted history cannot be recovered

Or we'll do it for you — Repair, A$89, no subscription: we trim the history when the check shows it's needed. Excluding noisy entities in configuration.yaml is still yours to do.

ElectriFix Perth Rockingham, WA Home Help guides Claude's robot Terms Privacy Refunds