recorder component is storing details in a database which then are handled by the
Home Assistant uses SQLAlchemy as Object Relational Mapper (ORM). This means that you can now use any SQL backend for the recorder that is supported by SQLAlchemy, like MySQL, MariaDB, PostgreSQL, or MS SQL Server.
The default database engine is SQLite which doesn’t require any configuration. The database is stored in your Home Assistant configuration directory (
.homeassistant) and called
To setup the
recorder component in your installation, add the following to your
# Example configuration.yaml entry recorder:
- purge_interval (Optional): (days) Enable scheduled purge of older events and states. The purge task runs every x days, starting from when Home Assistant is started. If you restart your instance more frequently, than the purge will never take place. You can use service call
- purge_keep_days (Required with
purge_interval): Specify number of history days to keep in recorder database after purge.
- exclude (Optional): Configure which components should be excluded from recordings.
- entities (Optional): The list of entity ids to be excluded from recordings.
- domains (Optional): The list of domains to be excluded from recordings.
- include (Optional): Configure which components should be included in recordings. If set, all other entities will not be recorded.
- entities (Optional): The list of entity ids to be included from recordings.
- domains (Optional): The list of domains to be included from recordings.
- db_url (Optional): The URL which point to your database.
Define domains and entities to
exclude (aka. blacklist). This is convenient when you are basically happy with the information recorded, but just want to remove some entities or domains. Usually these are entities/domains which do not change (like
weblink) or rarely change (
# Example configuration.yaml entry with exclude recorder: purge_interval: 2 purge_keep_days: 5 db_url: sqlite:///home/user/.homeassistant/test exclude: domains: - automation - weblink - updater entities: - sun.sun # Don't record sun data - sensor.last_boot - sensor.date
Define domains and entities to record by using the
include configuration (aka. whitelist). If you have a lot of entities in your system and your
exclude lists possibly get very large, 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
include list to define the domains/entities to record, and exclude some of them with in 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
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
If you only want to hide events from e.g. your history, take a look at the
history component. Same goes for logbook. But if you have privacy concerns about certain events or neither want them in history or logbook, you should use the
include options of the
recorder component, that they aren’t even in your database. That way you can save storage and keep the database small by excluding certain often-logged events (like
Call the service
recorder.purge to start purge task, which deletes events and states older than x days, according to
keep_days service data (Required)
Automation action example:
action: service: recorder.purge data: keep_days: 5
Custom database engines
|MS SQL Server||
Not all Python bindings for the chosen database engine can be installed directly. This section contains additional details which should help you to get it working.
For MariaDB you may have to install a few dependencies. On the Python side we use the
$ 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
$ sudo apt-get install default-libmysqlclient-dev libssl-dev $ pip3 install mysqlclient
If you are in a virtual environment, don’t forget to activate it before installing the
mysqlclient Python package.
[email protected]:~ $ sudo su homeassistant -s /bin/bash [email protected]:~$ source /srv/homeassistant/bin/activate (homeassistant) [email protected]:~$ 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.
Once Home Assistant finds the database, with right level of permissions, all the required tables will then be automatically created and the data will be populated accordingly.
For PostgreSQL you may have to install a few dependencies:
$ sudo apt-get install postgresql-server-dev-X.Y $ pip3 install psycopg2
For MS SQL Server you may have to install a few dependencies:
$ sudo apt-get install freetds-dev $ pip3 install pymssql
If you are in a virtual environment, don’t forget to activate it before installing the pymssql package.
$ sudo su -s /bin/bash homeassistant $ source /srv/homeassistant/bin/activate $ pip3 install pymssql