The recorder integration is responsible for storing details in a database, which then are handled by the history integration.

This integration constantly saves data. If you use the default configuration, the data will be saved on the media Home Assistant is installed on. In case of Raspberry Pi with an SD card, it might affect your system’s reaction time and life expectancy of the storage medium (the SD card). It is therefore recommended to set the commit_interval to higher value, e.g. 30s, limit the amount of stored data (e.g., by excluding devices) or store the data elsewhere (e.g., another system).

Home Assistant uses SQLAlchemy, which is an Object Relational Mapper (ORM). This makes it possible to use a number of database solutions.

The supported database solutions are:

Although SQLAlchemy supports additional database solutions, it will behave differently on different databases, and features relied on by the recorder may work differently, or not at all, in different databases.

The default, and recommended, database engine is SQLite which does not require any configuration. The database is stored in your Home Assistant configuration directory (’/config/’) and is named home-assistant_v2.db.

To change the defaults for the recorder integration in your installation, add the following to your configuration.yaml file:

# Example configuration.yaml entry

Configuration Variables

recorder map Required

Enables the recorder integration. Only allowed once.

db_url string (Optional)

The URL that points to your database. Examples of these can be found here.

db_max_retries integer (Optional, default: 10)

The max amount of times, the recorder retries to connect to the database.

db_retry_wait integer (Optional, default: 3)

The time in seconds, that the recorder sleeps when trying to connect to the database.

auto_purge boolean (Optional, default: true)

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 periodically.

purge_keep_days integer (Optional, default: 10)

Specify the number of history days to keep in recorder database after a purge.

commit_interval integer (Optional, default: 1)

How often (in seconds) the events and state changes are committed to the database. The default of 1 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 logbook and history will lag. If this is set to 0 (zero), commit are made as soon as possible after an event is processed.

exclude map (Optional)

Configure which integrations should be excluded from recordings. (Configure Filter)

domains list (Optional)

The list of domains to be excluded from recordings.

entity_globs list (Optional)

Exclude all entities matching a listed pattern from recordings (e.g., sensor.weather_*).

entities list (Optional)

The list of entity ids to be excluded from recordings.

event_types list (Optional)

The list of event types to be excluded from recordings.

include map (Optional)

Configure which integrations should be included in recordings. If set, all other entities will not be recorded. (Configure Filter)

domains list (Optional)

The list of domains to be included in the recordings.

entity_globs list (Optional)

Include all entities matching a listed pattern from recordings (e.g., sensor.weather_*).

entities list (Optional)

The list of entity ids to be included in the recordings.

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
      - alarm_control_panel
      - light
      - binary_sensor.*_occupancy
      - light.kitchen_light

Filters are applied as follows:

  1. No includes or excludes - pass all entities
  2. Includes, no excludes - only include specified entities
  3. Excludes, no includes - only exclude specified entities
  4. Both includes and excludes:
    • Include domain and/or glob patterns specified
      • If domain is included, and entity not excluded or match exclude glob pattern, pass
      • If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass
      • If domain is not included, glob pattern does not match, and entity not included, fail
    • Exclude domain and/or glob patterns specified and include does not list domains or glob patterns
      • If domain is excluded and entity not included, fail
      • If entity matches exclude glob pattern and entity not included, fail
      • If entity does not match any exclude criteria (domain, glob pattern or listed), pass
    • Neither include or exclude specifies domains or glob patterns
      • If entity is included, pass (as #2 above)
      • If entity include and exclude, the entity exclude is ignored

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
  purge_keep_days: 5
  db_url: sqlite:////home/user/.homeassistant/test
      - automation
      - updater
      - sensor.weather_*
      - sun.sun # Don't record sun data
      - sensor.last_boot # Comes from 'systemmonitor' sensor platform
      - 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
      - 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
      - sensor
      - switch
      - media_player
      - sensor.last_boot
      - sensor.weather_*


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 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.
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

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. Note: leaving all three parameters empty will result in all entities being selected for purging.

Service data attribute Optional Description
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.
entity_globs yes A list of regular expressions that identify entities to purge from the recorder database.

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.

Recommended engines and minimum versions

The following database engines are tested when major changes are made to the recorder. Other database engines do not have an active core maintainer at this time and may require additional work to maintain.

  • SQLite ≥ 3.32.1
  • MariaDB ≥ 10.3
  • MySQL ≥ 8.0
  • PostgreSQL ≥ 12

Custom database engines

Here are examples to use with the db_url configuration option.



MariaDB (omit pymysql)

mysql://user:[email protected]_IP/DB_NAME?charset=utf8mb4

MariaDB (omit pymysql, using TLS encryption)

mysql://user:[email protected]_IP/DB_NAME?charset=utf8mb4;ssl=true

MariaDB (omit pymysql, Socket)

mysql://user:[email protected]_IP/DB_NAME?unix_socket=/var/run/mysqld/mysqld.sock&charset=utf8mb4


mysql://user:[email protected]_IP/DB_NAME?charset=utf8mb4

MySQL (using TLS encryption)

mysql://user:[email protected]_IP/DB_NAME?charset=utf8mb4;ssl=true

MySQL (Socket)

mysql://user:[email protected]/DB_NAME?unix_socket=/var/run/mysqld/mysqld.sock&charset=utf8mb4


mysql+pymysql://user:[email protected]_IP/DB_NAME?charset=utf8mb4

MariaDB (Socket)

mysql+pymysql://user:[email protected]/DB_NAME?unix_socket=/var/run/mysqld/mysqld.sock&charset=utf8mb4


postgresql://user:[email protected]_IP/DB_NAME

PostgreSQL (Socket)


PostgreSQL (Custom socket dir)


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:

Description=Home Assistant 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

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 version 10.2, libmariadbclient-dev was renamed to libmariadb-dev. If you’re using MariaDB 10.3, the package libmariadb-dev-compat must also be installed. For MariaDB v10.0.34 only libmariadb-dev-compat is needed. 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.

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.


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();"
(1 row)

A service restart will work as well.