Skip to content

Commit

Permalink
Update recorder documentation according to ADR18 (#20145)
Browse files Browse the repository at this point in the history
  • Loading branch information
emontnemery authored Nov 4, 2021
1 parent 6c21cda commit b0bef9e
Showing 1 changed file with 14 additions and 44 deletions.
58 changes: 14 additions & 44 deletions source/_integrations/recorder.markdown
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,17 @@ This integration constantly saves data. If you use the default configuration, th

</div>

Home Assistant uses [SQLAlchemy](https://www.sqlalchemy.org/), which is an Object Relational Mapper (ORM). This means that you can use **any** SQL backend for the recorder that is supported by SQLAlchemy, like [MySQL](https://www.mysql.com/), [MariaDB](https://mariadb.org/), [PostgreSQL](https://www.postgresql.org/), or [MS SQL Server](https://www.microsoft.com/en-us/sql-server/).
Home Assistant uses [SQLAlchemy](https://www.sqlalchemy.org/), which is an Object Relational Mapper (ORM). This makes it possible to use a number of database solutions.

The default database engine is [SQLite](https://www.sqlite.org/) which does not require any configuration. The database is stored in your Home Assistant configuration directory ('/config/') and is named `home-assistant_v2.db`.
The supported database solutions are:
- [MariaDB](https://mariadb.org/) ≥ 10.3
- [MySQL](https://www.mysql.com/) ≥ 8.0
- [PostgreSQL](https://www.postgresql.org/) ≥ 12
- [SQLite](https://www.sqlite.org/) ≥ 3.32.1

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](https://www.sqlite.org/) 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:

Expand Down Expand Up @@ -231,10 +239,10 @@ Call the service `recorder.enable` to start again saving events and states to th

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 5.7+
- PostgreSQL 12+
- SQLite 3.32.1
- MariaDB 10.3
- MySQL ≥ 8.0
- PostgreSQL ≥ 12

## Custom database engines

Expand Down Expand Up @@ -278,13 +286,6 @@ PostgreSQL (Socket):
PostgreSQL (Custom socket dir):
description: >
`postgresql://@/DB_NAME?host=/path/to/dir`
MS SQL Server:
description: >
`mssql+pyodbc://username:password@SERVER_IP:1433/DB_NAME?charset=utf8&driver=DRIVER`
Oracle:
description: >
`oracle+cx_oracle://username:password@SERVER_IP:1521/DB_NAME?encoding=UTF-8&nencoding=UTF-8`
{% endconfiguration_basic %}

<div class='note'>
Expand Down Expand Up @@ -313,12 +314,6 @@ If you want to use Unix Sockets for PostgreSQL you need to modify the `pg_hba.co

</div>

<div class='note warning'>

If you are using the default `FULL` recovery model for MS SQL Server you will need to manually backup your log file to prevent your transaction log from growing too large. It is recommended you change the recovery model to `SIMPLE` unless you are worried about data loss between backups.

</div>

### 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.
Expand Down Expand Up @@ -415,28 +410,3 @@ $ sudo -i -u postgres psql -c "SELECT pg_reload_conf();"
(1 row)
```
A service restart will work as well.

### MS SQL Server

For MS SQL Server you will have to install a few dependencies:

```bash
sudo apt-get install unixodbc-dev
pip3 install pyodbc
```

If you are in a virtual environment, don't forget to activate it before installing the pyodbc package.

```bash
sudo -u homeassistant -H -s
source /srv/homeassistant/bin/activate
pip3 install pyodbc
```

You will also need to install an ODBC Driver. Microsoft ODBC drivers are recommended, however FreeTDS is available for systems that are not supported by Microsoft. Instructions for installing the Microsoft ODBC drivers can be found [here](https://docs.microsoft.com/en-us/sql/connect/odbc/linux-mac/installing-the-microsoft-odbc-driver-for-sql-server).

<div class='note'>

If you are using Hass.io, FreeTDS is already installed for you. The db_url you need to use is `mssql+pyodbc://username:password@SERVER_IP:1433/DB_NAME?charset=utf8mb4&driver=FreeTDS`.

</div>

0 comments on commit b0bef9e

Please sign in to comment.