Update recorder documentation according to ADR18 (#20145)

This commit is contained in:
Erik Montnemery 2021-11-04 08:45:34 +01:00 committed by GitHub
parent 6c21cda742
commit b0bef9ea4e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -19,9 +19,17 @@ This integration constantly saves data. If you use the default configuration, th
</div> </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: To change the defaults for the `recorder` integration in your installation, add the following to your `configuration.yaml` file:
@ -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. 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+ - SQLite 3.32.1
- MariaDB 10.3+ - MariaDB 10.3
- MySQL 5.7+ - MySQL ≥ 8.0
- PostgreSQL 12+ - PostgreSQL 12
## Custom database engines ## Custom database engines
@ -278,13 +286,6 @@ PostgreSQL (Socket):
PostgreSQL (Custom socket dir): PostgreSQL (Custom socket dir):
description: > description: >
`postgresql://@/DB_NAME?host=/path/to/dir` `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 %} {% endconfiguration_basic %}
<div class='note'> <div class='note'>
@ -313,12 +314,6 @@ If you want to use Unix Sockets for PostgreSQL you need to modify the `pg_hba.co
</div> </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 ### 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. 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.
@ -415,28 +410,3 @@ $ sudo -i -u postgres psql -c "SELECT pg_reload_conf();"
(1 row) (1 row)
``` ```
A service restart will work as well. 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>