Recorder
The Recorder integration is the component that writes WoowTech's history into a database. It loads by default because the history integration depends on it, and under the hood it talks to the database through SQLAlchemy, which is why it can target several different database engines without any change to your setup.
Which databases work
| Engine | Minimum version |
|---|---|
| SQLite | 3.40.1 |
| MariaDB | 10.3 |
| MySQL | 8.0 |
| PostgreSQL | 12 |
Out of the box you get SQLite, and for most people that is the right choice — it needs no configuration whatsoever. WoowTech keeps its data in a file named home-assistant_v2.db inside the configuration directory.
Keep spare disk free
Treat free disk as a hard requirement, not a nicety. At every moment you should have at least as much temporary space available as the database itself occupies, because upgrades and housekeeping jobs occasionally spin up a temporary copy of the whole database. If your database has grown to 1.5 GiB, then 1.5 GiB of headroom needs to stay free continuously.
Turning it on and tuning it
The integration activates with nothing more than:
recorder:
The settings below let you change how aggressively it writes and how long it keeps things.
| Option | Default | What it governs |
|---|---|---|
db_url |
(SQLite file) | A custom connection string pointing at an external database. |
db_max_retries |
10 | How many times to retry a failed database connection before giving up. |
db_retry_wait |
3 (seconds) | The pause between those connection retries. |
auto_purge |
true | Run the nightly cleanup automatically at 04:12 local time. |
auto_repack |
true | Compact the database on the second Sunday of each month. |
purge_keep_days |
10 | How many days of history to keep when a purge runs. |
commit_interval |
5 (seconds) | How often buffered events are flushed to disk. |
Choosing what gets recorded
By default everything is stored, but you can narrow that with include and exclude. Both accept domains, entities, and glob-based entity_globs, where * matches any run of characters and ? matches a single optional character.
recorder:
include:
domains:
- climate
- binary_sensor
entity_globs:
- light.kitchen_*
exclude:
entities:
- sensor.uptime_seconds
domains:
- automation
Actions you can call
| Action | Purpose |
|---|---|
recorder.purge |
Drops events older than a given number of days. Note that this frees rows but does not instantly hand the disk space back. |
recorder.purge_entities |
Clears records for specific entity IDs, whole domains, or glob patterns. |
recorder.disable / recorder.enable |
Pauses and later resumes writing to the database. |
recorder.get_statistics |
Reads back long-term statistics (mean, min, max, sum) for entities that support them. |
Getting better performance
On a Raspberry Pi, or any setup writing to an SD card, the constant small writes wear the card and slow things down. Stretching commit_interval out to 30 seconds collapses many writes into fewer, larger ones and prolongs the card's life. You can also trim what you store by excluding chatty, high-frequency entities, or move the whole database onto an external engine such as MariaDB or PostgreSQL.
recorder:
commit_interval: 30
exclude:
entities:
- sensor.power_draw_watts
Recovering from a damaged database
When SQLite hits corruption it cannot repair, it sets the broken file aside and starts a fresh database in its place — so recording simply continues. Because this move-and-rebuild needs room for a copy, keep roughly 2.5 times the database size free for it to work. If you would rather salvage the data, SQLite's own recovery tooling can sometimes rescue the original file.
Recorder
The Recorder integration is the component that writes WoowTech's history into a database. It loads by default because the history integration depends on it, and under the hood it talks to the database through SQLAlchemy, which is why it can target several different database engines without any change to your setup.
Which databases work
| Engine | Minimum version |
|---|---|
| SQLite | 3.40.1 |
| MariaDB | 10.3 |
| MySQL | 8.0 |
| PostgreSQL | 12 |
Out of the box you get SQLite, and for most people that is the right choice — it needs no configuration whatsoever. WoowTech keeps its data in a file named home-assistant_v2.db inside the configuration directory.
Keep spare disk free
Treat free disk as a hard requirement, not a nicety. At every moment you should have at least as much temporary space available as the database itself occupies, because upgrades and housekeeping jobs occasionally spin up a temporary copy of the whole database. If your database has grown to 1.5 GiB, then 1.5 GiB of headroom needs to stay free continuously.
Turning it on and tuning it
The integration activates with nothing more than:
recorder:
The settings below let you change how aggressively it writes and how long it keeps things.
| Option | Default | What it governs |
|---|---|---|
db_url |
(SQLite file) | A custom connection string pointing at an external database. |
db_max_retries |
10 | How many times to retry a failed database connection before giving up. |
db_retry_wait |
3 (seconds) | The pause between those connection retries. |
auto_purge |
true | Run the nightly cleanup automatically at 04:12 local time. |
auto_repack |
true | Compact the database on the second Sunday of each month. |
purge_keep_days |
10 | How many days of history to keep when a purge runs. |
commit_interval |
5 (seconds) | How often buffered events are flushed to disk. |
Choosing what gets recorded
By default everything is stored, but you can narrow that with include and exclude. Both accept domains, entities, and glob-based entity_globs, where * matches any run of characters and ? matches a single optional character.
recorder:
include:
domains:
- climate
- binary_sensor
entity_globs:
- light.kitchen_*
exclude:
entities:
- sensor.uptime_seconds
domains:
- automation
Actions you can call
| Action | Purpose |
|---|---|
recorder.purge |
Drops events older than a given number of days. Note that this frees rows but does not instantly hand the disk space back. |
recorder.purge_entities |
Clears records for specific entity IDs, whole domains, or glob patterns. |
recorder.disable / recorder.enable |
Pauses and later resumes writing to the database. |
recorder.get_statistics |
Reads back long-term statistics (mean, min, max, sum) for entities that support them. |
Getting better performance
On a Raspberry Pi, or any setup writing to an SD card, the constant small writes wear the card and slow things down. Stretching commit_interval out to 30 seconds collapses many writes into fewer, larger ones and prolongs the card's life. You can also trim what you store by excluding chatty, high-frequency entities, or move the whole database onto an external engine such as MariaDB or PostgreSQL.
recorder:
commit_interval: 30
exclude:
entities:
- sensor.power_draw_watts
Recovering from a damaged database
When SQLite hits corruption it cannot repair, it sets the broken file aside and starts a fresh database in its place — so recording simply continues. Because this move-and-rebuild needs room for a copy, keep roughly 2.5 times the database size free for it to work. If you would rather salvage the data, SQLite's own recovery tooling can sometimes rescue the original file.
Start writing here...