# Example configuration.yaml entry
recorder:
 Configuration Variables
Looking for your configuration file?
  recorder map Required
Enables the recorder integration. Only allowed once.
  auto_repack boolean (Optional, default: true)
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 periodically. This flag has no effect if auto_purge is disabled.
  commit_interval integer (Optional, default: 5)
How often (in seconds) the events and state changes are committed to the database. The default of 5 allows events to be committed almost right away without trashing the disk when an event storm happens. Increasing this will reduce disk I/O and may prolong disk (SD card) lifetime with the trade-off being that the database will lag (the logbook and history will not lag, because the changes are streamed to them immediatelly). If this is set to 0 (zero), commit are made as soon as possible after an event is processed.
 Configure Filter
By default, no entity will be excluded. To limit which entities are being exposed to recorder, you can use the include and exclude parameters.
# Example filter to include specified domains and exclude specified entities
recorder:
  include:
    domains:
      - alarm_control_panel
      - light
    entity_globs:
      - binary_sensor.*_occupancy
  exclude:
    entities:
      - light.kitchen_light
Filters are applied as follows:
No filter
All entities included
Only includes
Entity listed in entities include: include
Otherwise, entity matches domain include: include
Otherwise, entity matches glob include: include
Otherwise: exclude
Only excludes
Entity listed in exclude: exclude
Otherwise, entity matches domain exclude: exclude
Otherwise, entity matches glob exclude: exclude
Otherwise: include
Domain and/or glob includes (may also have excludes)
Entity listed in entities include: include
Otherwise, entity listed in entities exclude: exclude
Otherwise, entity matches glob include: include
Otherwise, entity matches glob exclude: exclude
Otherwise, entity matches domain include: include
Otherwise: exclude
Domain and/or glob excludes (no domain and/or glob includes)
Entity listed in entities include: include
Otherwise, entity listed in exclude: exclude
Otherwise, entity matches glob exclude: exclude
Otherwise, entity matches domain exclude: exclude
Otherwise: include
No Domain and/or glob includes or excludes
Entity listed in entities include: include
Otherwise: exclude
The following characters can be used in entity globs:
* - The asterisk represents zero, one, or multiple characters
? - The question mark represents a single character
If you only want to hide events from your history, take a look at the history integration. The same goes for the logbook. But if you have privacy concerns about certain events or want them in neither the history or logbook, you should use the exclude/include options of the recorder integration. That way they aren’t even in your database, you can reduce storage and keep the database small by excluding certain often-logged events (like sensor.last_boot).
 Common filtering examples
Defining domains and entities to exclude (i.e. blocklist) is convenient when you are basically happy with the information recorded, but just want to remove some entities or domains.
# Example configuration.yaml entry with exclude
recorder:
  purge_keep_days: 5
  db_url: sqlite:////home/user/.homeassistant/test
  exclude:
    domains:
      - automation
      - update
    entity_globs:
      - sensor.sun*
      - weather.*
    entities:
      - sensor.date
      - sensor.last_boot # Comes from 'systemmonitor' sensor platform
      - sun.sun # Don't record sun data
    event_types:
      - call_service # Don't record service calls
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.
# Example configuration.yaml entry with include
recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player
You can also use the include list to define the domains/entities to record, and exclude some of those within the exclude list. This makes sense if you, for instance, include the sensor domain, but want to exclude some specific sensors. Instead of adding every sensor entity to the include entities list just include the sensor domain and exclude the sensor entities you are not interested in.
# Example configuration.yaml entry with include and exclude
recorder:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*
 Services
 Service 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.
Note that purging will not immediately decrease disk space usage but it will significantly slow down further growth.
Service data attribute
Optional
Description
keep_days
The number of history days to keep in recorder database (defaults to the integration purge_keep_days configuration)
repack
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
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.
entity_globs
A list of regular expressions that identify entities to purge from the recorder database.
keep_days
Number of history days to keep in the database of matching rows. The default of 0 days will remove all matching rows.
Note: The entity_id is only optional when used in automations.yaml or scripts.yaml. When using the UI to call this service then it is mandatory to specify at least one entity_id using the Target Picker or via YAML mode.
 Example automation to remove data rows for specific entities
The below automation will remove history for sensor.power_sensor_0 older than 5 days at 04:15:00 every day.
alias: "Purge noisy power sensors"
trigger:
  - platform: time
    at: "04:15:00"
action:
  - service: recorder.purge_entities
    data:
      keep_days: 5
    target:
      entity_id: sensor.power_sensor_0
mode: single
 Service disable
Call the service recorder.disable to stop saving events and states to the database.
 Service enable
Call the service recorder.enable to start again saving events and states to the database. This is the opposite of recorder.disable.
 Custom database engines
SQLite is the most tested, and newer version of Home Assistant are highly optimized to perform well when using SQLite.
When choosing another option, you should be comfortable in the role of the database administrator, including making backups of the external database.
Here are examples to use with the db_url configuration option.
Some installations of MariaDB/MySQL may require an ALTERNATE_PORT (3rd-party hosting providers or parallel installations) to be added to the SERVER_IP, e.g., mysql://user:[email protected]_IP:ALTERNATE_PORT/DB_NAME?charset=utf8mb4.
When using a MariaDB or MySQL server, adding +pymysql to the URL will use the pure Python MySQL library, which is slower but may be required if the C MySQL library is not available.
When using the official Docker image, the C MySQL library will always be available. pymysql is most commonly used with venv where the C MySQL library is not installed.
Unix Socket connections always bring performance advantages over TCP, if the database is on the same host as the recorder instance (i.e., localhost).
If you want to use Unix Sockets for PostgreSQL you need to modify the pg_hba.conf. See PostgreSQL
 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.
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.
sudo nano /etc/systemd/system/[email protected]
and add the service for the database, for example, PostgreSQL:
[Unit]
Description=Home Assistant
After=network.target postgresql.service
Save the file then reload systemctl:
sudo systemctl daemon-reload
 Installation notes
Not all Python bindings for the chosen database engine can be installed directly. This section contains additional details that should help you to get it working.
 MariaDB and MySQL
MariaDB versions before 10.5.17, 10.6.9, 10.7.5, and 10.8.4 suffer from a performance regression which can result in the system becoming overloaded while querying history data or purging the database.
Make sure the default character set of your database server is set to utf8mb4 (see MariaDB documentation).
If you are in a virtual environment, don’t forget to activate it before installing the mysqlclient Python package described below.
[email protected]:~ $ sudo -u homeassistant -H -s
[email protected]:~$ source /srv/homeassistant/bin/activate
(homeassistant) [email protected]:~$ pip3 install mysqlclient
For MariaDB you may have to install a few dependencies. If you’re using MariaDB 10.3, the package libmariadb-dev-compat must also be installed. Please install the correct packages based on your MariaDB version.
On the Python side we use the mysqlclient:
sudo apt-get install libmariadbclient-dev libssl-dev
pip3 install mysqlclient
For MySQL you may have to install a few dependencies. You can choose between pymysql and mysqlclient:
sudo apt-get install default-libmysqlclient-dev libssl-dev
pip3 install mysqlclient
After installing the dependencies, it is required to create the database manually. During the startup, Home Assistant will look for the database specified in the db_url. If the database doesn’t exist, it will not automatically create it for you.
The database engine must be InnoDB as MyIASM is not supported.
SET GLOBAL default_storage_engine = 'InnoDB';
CREATE DATABASE DB_NAME CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
Where DB_NAME is the name of your database
Once Home Assistant finds the database, with the right level of permissions, all the required tables will then be automatically created and the data will be populated accordingly.
 PostgreSQL
Create the PostgreSQL database with utf8 encoding. The PostgreSQL default encoding is SQL_ASCII. From the postgres user account;
createdb -E utf8 DB_NAME
Where DB_NAME is the name of your database
If the Database in use is not utf8, adding ?client_encoding=utf8 to the db_url may solve any issue.
For PostgreSQL you may have to install a few dependencies:
sudo apt-get install postgresql-server-dev-X.Y
pip3 install psycopg2
For using Unix Sockets, first create your user from the postgres user account;
createuser USER_NAME
Where USER_NAME is the name of the user running the Home Assistant instance (see securing your installation).
Then add the following line to your pg_hba.conf:
local DB_NAME USER_NAME peer
Where DB_NAME is the name of your database and USER_NAME is the name of the user running the Home Assistant instance (see securing your installation).
Reload the PostgreSQL configuration after that:
$ sudo -i -u postgres psql -c "SELECT pg_reload_conf();"
 pg_reload_conf
----------------
(1 row)
A service restart will work as well.
 Help us to improve our documentation
Suggest an edit to this page, or provide/view feedback for this page.
 Provide feedback
 View pending feedback
The Recorder system was introduced in Home Assistant pre 0.7, and it's used by 
99.3% of the active installations.
Its IoT class is Local Push
and it
scores internal on our quality scale.
 View source on GitHub

 View known issues
Categories
History