jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 07:17:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

database docs and recorder integration: (#33798)

Browse Source
This commit is contained in:
c0ffeeca7 2024-07-16 15:57:18 +02:00 committed by GitHub
parent fa7cd2831a
commit a238cfc5e5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 17 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
source/_docs/backend/database.markdown
View File

@ -127,6 +127,6 @@ group.all_switches 8018
### Delete ### Delete
If you don't want to keep certain entities, you can delete them permanently by using the [services provided by the recorder](/integrations/recorder/#service-purge_entities). If you don't want to keep certain entities, you can delete them permanently by using the [actions provided by the recorder](/integrations/recorder/#action-purge_entities).
For a more interactive way of working with the database, check the [Data Science Portal](https://data.home-assistant.io/). For a more interactive way of working with the database, check the [Data Science Portal](https://data.home-assistant.io/).

32
source/_integrations/recorder.markdown
View File

@ -62,12 +62,12 @@ recorder:
default: 3 default: 3
type: integer type: integer
auto_purge: auto_purge:
description: Automatically purge the database every night at 04:12 local time. Purging keeps the database from growing indefinitely, which takes up disk space and can make Home Assistant slow. If you disable `auto_purge` it is recommended that you create an automation to call the [`recorder.purge`](#service-purge) periodically. description: Automatically purge the database every night at 04:12 local time. Purging keeps the database from growing indefinitely, which takes up disk space and can make Home Assistant slow. If you disable `auto_purge` it is recommended that you create an automation to call the [`recorder.purge`](#action-purge) periodically.
required: false required: false
default: true default: true
type: boolean type: boolean
auto_repack: auto_repack:
description: Automatically repack the database every second sunday after the auto purge. Without a repack, the database may not decrease in size even after purging, which takes up disk space and can make Home Assistant slow. If you disable `auto_repack` it is recommended that you create an automation to call the [`recorder.purge`](#service-purge) periodically. This flag has no effect if `auto_purge` is disabled. description: Automatically repack the database every second sunday after the auto purge. Without a repack, the database may not decrease in size even after purging, which takes up disk space and can make Home Assistant slow. If you disable `auto_repack` it is recommended that you create an automation to call the [`recorder.purge`](#action-purge) periodically. This flag has no effect if `auto_purge` is disabled.
required: false required: false
default: true default: true
type: boolean type: boolean
@ -164,7 +164,7 @@ recorder:
- sensor.last_boot # Comes from 'systemmonitor' sensor platform - sensor.last_boot # Comes from 'systemmonitor' sensor platform
- sun.sun # Don't record sun data - sun.sun # Don't record sun data
event_types: event_types:
- call_service # Don't record service calls - call_service # Don't record actions
``` ```
Defining domains and entities to record by using the `include` configuration (i.e. allowlist) is convenient if you have a lot of entities in your system and your `exclude` lists possibly get very large, so it might be better just to define the entities or domains to record. Defining domains and entities to record by using the `include` configuration (i.e. allowlist) is convenient if you have a lot of entities in your system and your `exclude` lists possibly get very large, so it might be better just to define the entities or domains to record.
@ -197,24 +197,24 @@ recorder:
- sensor.weather_* - sensor.weather_*
``` ```
## Services ## Actions
### Service `purge` ### Action `purge`
Call the service `recorder.purge` to start a purge task which deletes events and states older than x days, according to `keep_days` service data. Perform the action `recorder.purge` to start a purge task which deletes events and states older than x days, according to `keep_days` action data.
Note that purging will not immediately decrease disk space usage but it will significantly slow down further growth. Note that purging will not immediately decrease disk space usage but it will significantly slow down further growth.
| Service data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `keep_days` | yes | The number of history days to keep in recorder database (defaults to the integration `purge_keep_days` configuration) | | `keep_days` | yes | The number of history days to keep in recorder database (defaults to the integration `purge_keep_days` configuration) |
| `repack` | yes | When using SQLite or PostgreSQL this will rewrite the entire database. When using MySQL or MariaDB it will optimize or recreate the events and states tables. This is a heavy operation that can cause slowdowns and increased disk space usage while it runs. Only supported by SQLite, PostgreSQL, MySQL and MariaDB. | | `repack` | yes | When using SQLite or PostgreSQL this will rewrite the entire database. When using MySQL or MariaDB it will optimize or recreate the events and states tables. This is a heavy operation that can cause slowdowns and increased disk space usage while it runs. Only supported by SQLite, PostgreSQL, MySQL and MariaDB. |
| `apply_filter` | yes | Apply entity_id and event_type filter in addition to time based purge. Useful in combination with `include` / `exclude` filter to remove falsely added states and events. Combine with `repack: true` to reduce database size. | | `apply_filter` | yes | Apply entity_id and event_type filter in addition to time based purge. Useful in combination with `include` / `exclude` filter to remove falsely added states and events. Combine with `repack: true` to reduce database size. |
### Service `purge_entities` ### Action `purge_entities`
Call the service `recorder.purge_entities` to start a task that purges events and states from the recorder database that match any of the specified `entity_id`, `domains`, and `entity_globs` fields. At least one of the three selection criteria fields must be provided. Perform the action `recorder.purge_entities` to start a task that purges events and states from the recorder database that match any of the specified `entity_id`, `domains`, and `entity_globs` fields. At least one of the three selection criteria fields must be provided.
| Service data attribute | Optional | Description | | Data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | yes | A list of entity_ids that should be purged from the recorder database. | | `entity_id` | yes | A list of entity_ids that should be purged from the recorder database. |
| `domains` | yes | A list of domains that should be purged from the recorder database. | | `domains` | yes | A list of domains that should be purged from the recorder database. |
@ -238,13 +238,13 @@ action:
mode: single mode: single
``` ```
### Service `disable` ### Action `disable`
Call the service `recorder.disable` to stop saving events and states to the database. Perform the action `recorder.disable` to stop saving events and states to the database.
### Service `enable` ### Action `enable`
Call the service `recorder.enable` to start again saving events and states to the database. This is the opposite of `recorder.disable`. Perform the action `recorder.enable` to start again saving events and states to the database. This is the opposite of `recorder.disable`.
## Custom database engines ## Custom database engines
@ -316,14 +316,14 @@ If you want to use Unix Sockets for PostgreSQL you need to modify the `pg_hba.co
### Database startup ### Database startup
If you are running a database server instance on the same server as Home Assistant then you must ensure that this service starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) you should edit the service file. If you are running a database server instance on the same server as Home Assistant then you must ensure that this action starts before Home Assistant. For a Linux instance running Systemd (Raspberry Pi, Debian, Ubuntu and others) you should edit the service file.
To help facilitate this, db_max_retry and db_retry_wait variables have been added to ensure the recorder retries the connection to your database enough times, for your database to start up. To help facilitate this, db_max_retry and db_retry_wait variables have been added to ensure the recorder retries the connection to your database enough times, for your database to start up.
```bash ```bash
sudo nano /etc/systemd/system/home-assistant@homeassistant.service sudo nano /etc/systemd/system/home-assistant@homeassistant.service
``` ```
and add the service for the database, for example, PostgreSQL: and add the action for the database, for example, PostgreSQL:
```txt ```txt
[Unit] [Unit]