Short Answer: Keep Recorder Small, Not Empty

The practical fix is: back up Home Assistant, find the noisy entities, stop recording the ones you do not need, then use Home Assistant's recorder purge actions instead of editing the database by hand. For most homes, the right recorder setting is not forever and not zero. It is usually the default 10 days, or a similar short window, plus long-term statistics for the numbers you actually care about over months and years.

The recorder is Home Assistant's local history database. It stores state changes and events so History, Logbook, Energy Dashboard, statistics, and some diagnostics can look backward. An entity is one named thing Home Assistant tracks, such as sensor.freezer_temperature, switch.desk_plug, or binary_sensor.front_door. A single bad entity that changes every few seconds can fill more disk than hundreds of quiet lights and contact sensors.

Do not make the database problem bigger by immediately moving to MariaDB, deleting files, or copying SQL from an old forum answer. Home Assistant's current recorder docs say SQLite is the default and recommended engine, auto-purge is enabled by default, and repack can be heavy. Start with the supported path, then escalate only if the database is already huge, corrupt, or too large to back up safely.

Why the Database Gets Big

Home Assistant constantly saves recorder data. That is useful: it lets the house explain what happened yesterday when the porch light stayed on, when the freezer warmed up, or when an automation did not run. The problem is that local history is not free. It lives on the storage Home Assistant uses, often an SSD, eMMC module, or SD card.

The current official recorder docs say the default database is SQLite, stored in /config/home-assistant_v2.db. SQLite is a small local database engine, not a cloud service. It is the right default for many homes because it needs no separate database server. Home Assistant also supports MariaDB, MySQL, and PostgreSQL, but its docs warn that changing the recorder database can lose existing history because migration is not supported.

The usual growth causes are plain:

  • Long raw retention: keeping 100, 365, or 1,825 days of detailed state history means every entity keeps far more rows.
  • Noisy sensors: power, RSSI, uptime, debug, BLE, weather, template, or camera-related sensors can report too often or with changing attributes.
  • Deleted experiments: old ESPHome, BLE, MQTT, or test devices may have left history behind.
  • Repack has not run yet: old rows may be deleted, but the file can stay large until the database is rewritten or optimized.
  • External database add-ons: MariaDB can move the problem into add-on data or backups, which makes the backup grow instead of the visible .db file.

The First 10-Minute Check

Before changing YAML, measure the problem.

  1. Check the estimated recorder size. Go to Settings > System > Repairs, open the three-dot menu, choose System information, and look under Recorder for the estimated database size. Home Assistant's common-tasks docs call out this exact check before backups and migrations.
  2. Check total disk use. In the same System information view, look under Supervisor disk usage if you run Home Assistant OS or Supervised. A 3 GB database is a different problem on a 32 GB appliance than on a mini PC with a large SSD.
  3. Make a full backup. A database cleanup is exactly the kind of work that deserves a fresh backup. Keep a copy outside Home Assistant before a large purge or repack.
  4. Check free space. Home Assistant's recorder docs say you should have at least as much free temporary space as the database size because rebuilds, repairs, repacks, and upgrades can copy data on disk. For a very large database, leave more than the bare minimum.
  5. Look for the loudest entity. If you are not comfortable with SQL, use History and Logbook first: the problem entity often appears as a sensor that changes constantly. If you are comfortable with SQL, use Home Assistant's SQL integration or a backup copy of the database, not a live destructive query.

What to Change in Recorder

Home Assistant's current defaults are intentionally conservative: auto_purge is on, purging runs nightly at 04:12 local time, auto_repack is on every second Sunday after purge, and purge_keep_days defaults to 10 days. That is a good baseline.

If your database is too large, the first setting to question is usually purge_keep_days. A longer raw history window keeps detailed data for every recorded entity. If you want a full year of energy, temperature, or water trends, that is usually a long-term statistics question, not a 365-day raw recorder question.

A cautious recorder configuration looks like this:

recorder:
  purge_keep_days: 10
  auto_purge: true
  auto_repack: true
  commit_interval: 30
  exclude:
    entity_globs:
      - sensor.*_rssi
      - sensor.*_debug*
    entities:
      - sensor.example_noisy_test_sensor

Do not paste that unchanged. Treat it as shape, not a universal answer. Some RSSI, debug, or diagnostic sensors are useful while you are installing a mesh, debugging Wi-Fi, or testing a device. The homeowner-safe rule is: record the things you would actually look up later, and exclude the things that only prove a device is chattering.

The Safe Cleanup Order

Step What it does Why this order matters
1. Back up Create a full backup and keep a copy outside Home Assistant. Database cleanup changes local history. A backup is your undo button.
2. Stop future noise Disable the bad entity or add recorder excludes, then restart if YAML changed. Purging without fixing the source only buys time.
3. Remove known noisy history Use Recorder: Purge entities for specific entities, domains, or globs. This targets the bad actor instead of erasing useful history everywhere.
4. Purge old rows Use Recorder: Purge with the keep-days value you actually want. This removes old events and state changes by age.
5. Repack only when needed Enable repack if you need the file on disk to shrink now. Repack is heavy, can slow Home Assistant, and can temporarily use more disk.

The important distinction is purge versus repack. Purge is the cleanup. Repack is the disk-space reclaim. Home Assistant's action docs say purge removes old events and state changes; the same page says repack rewrites the database to try to free disk space and can cause slowdowns or temporary extra disk use.

For a normal-size database, this may be uneventful. For a very large database, schedule a maintenance window. A recent r/homeassistant post about a 78 GB purge described hours of waiting, much higher CPU, and a large temporary disk-space spike. That is not a recipe to copy; it is a warning that a huge recorder file should be treated like maintenance, not a button to press five minutes before bed.

Do Not Confuse Raw History With Long-Term Statistics

This is the part that saves a lot of disk. Home Assistant keeps detailed short-term recorder data for the retention window, but it also has long-term statistics for eligible numeric sensors. The current recorder statistics action docs say short-term statistics are sampled every 5 minutes and purged after the predefined period, while long-term statistics are hourly aggregates and are never purged.

In plain English: you do not usually need to keep every raw watt reading forever to see energy history over a year. The yearly view should come from compact long-term statistics, not a giant raw table.

This is also why the Energy Dashboard can still show older trends after normal recorder purging, as long as the entity metadata and statistics are healthy. Home Assistant 2024.10 added repairs for long-term statistics so broken statistics are easier to notice and fix. If yearly energy or water history is the reason you made purge_keep_days enormous, check whether long-term statistics already give you the answer in a smaller, safer way.

What Not to Do

  • Do not disable recorder blindly. Home Assistant may keep running, but History, Logbook, statistics, Energy Dashboard behavior, and troubleshooting all get worse.
  • Do not set raw history to a year because it feels safer. It can make backups slow, upgrades risky, and small hardware feel broken.
  • Do not run random DELETE statements on the live database. SQLite, MariaDB, and Home Assistant's schema have relationships you can damage. Work from a backup copy if you need inspection.
  • Do not repack with a nearly full disk. The official docs require at least database-size free temporary space, and community reports show very large databases can need much more headroom in practice.
  • Do not upload your database to a public support thread. Recorder data can reveal household routines, device names, occupancy patterns, camera events, and other private history.

Should You Switch to MariaDB?

For most homeowners, no. Stay with SQLite unless you have a specific reason to run an external database and you understand the maintenance. Home Assistant's recorder docs call SQLite the default and recommended engine. It does not need a separate service, database password, add-on backup plan, or cross-machine availability.

MariaDB, MySQL, or PostgreSQL can make sense for advanced installs, especially if the database is on another machine and the owner knows how to back up and monitor it. But switching engines is not a magic shrink button. Home Assistant warns that changing recorder databases may lose existing history because migration is not supported. A bad retention plan in MariaDB is still a bad retention plan; it just fails differently.

If the house is on a Raspberry Pi SD card, the answer is usually not "use MariaDB first." The answer is better storage, fewer noisy entities, shorter raw retention, and a real backup plan. If the house is large enough to need external metrics, send selected long-term trend data to a purpose-built time-series tool while keeping Home Assistant's own recorder boring and recoverable.

What the Symptom Usually Means

What you see Most likely cause Best first move
Database grows every day but flattens overnight Normal daily recorder purge pattern Keep defaults unless backups or disk use are still too large.
Database or backup doubles quickly Noisy entity, renamed device, add-on database, or long retention Find the loudest entity and stop recording it before purging.
Purge ran but file size barely changed Rows removed but disk file not rewritten Use repack during maintenance if you need disk back now.
Energy history seems important, so keep_days is huge Raw history confused with long-term statistics Use long-term statistics for yearly trends and shorten raw retention.
History or Logbook is slow Very large database, slow storage, noisy sensors, or underpowered hardware Clean recorder first, then consider hardware or database changes.

Tara's Take

A local smart home should keep enough history to explain the house, not so much history that backups, upgrades, and restores become scary. Tara's default posture is short raw history, useful long-term statistics, boring local storage, and a backup plan that has been tested before a migration or major cleanup.

For installed homes, this is also a handoff issue. A homeowner should know where to check database size, what a normal backup size looks like, and which sensors are intentionally not recorded. That is more valuable than a heroic database tweak that only one person understands.

Recorder cleanup sits next to backup, update, hardware, and energy hygiene. These Tara guides are useful next.

FAQ

Can I just delete home-assistant_v2.db?

Only if you intentionally want to throw away recorder history and you have a backup. Home Assistant can recreate an empty database, but that is not the same as safely shrinking one. Use supported purge actions first.

Will purge delete my Energy Dashboard history?

Normal raw recorder history and short-term statistics follow the retention window. Long-term statistics are hourly summaries and are not purged by the normal short-term retention setting. That is why yearly energy views usually do not require a giant raw database.

Why did the database not shrink after I purged old data?

Purge removes old records. Repack reclaims disk space by rewriting or optimizing the database. If the file is still large after a purge, run repack only when you have spare disk space and can tolerate temporary slowdown.

Should I switch to MariaDB for a large Home Assistant database?

Not by default. SQLite is Home Assistant's recommended default. Switch only if you have a clear operational reason and you are ready to maintain and back up the external database.

How much free space should I leave before repack?

At minimum, leave free temporary space equal to the database size, because Home Assistant says rebuilds, repairs, repacks, and upgrades can copy data. For a very large recorder database, leave more than the minimum.