Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update recorder documentation according to ADR18 #20145

Merged
merged 1 commit into from
Nov 4, 2021
Merged

Update recorder documentation according to ADR18 #20145

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update recorder documentation according to ADR18
  • Loading branch information
@emontnemery
emontnemery authored Nov 4, 2021
commit 08d434e4a3550af3434e1eba4e7dfdce7cdf5789
58 changes: 14 additions & 44 deletions source/_integrations/recorder.markdown
View file
Open in desktop
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>