From 30097b38dfbcc5bbd34345a6f3a95378705c1ab4 Mon Sep 17 00:00:00 2001 From: G Johansson Date: Sun, 24 Apr 2022 20:52:33 +0200 Subject: [PATCH] Update sql for config flow (#22162) --- source/_integrations/sql.markdown | 143 +++++------------------------- 1 file changed, 24 insertions(+), 119 deletions(-) diff --git a/source/_integrations/sql.markdown b/source/_integrations/sql.markdown index e75e4410fc1..5f20a446744 100644 --- a/source/_integrations/sql.markdown +++ b/source/_integrations/sql.markdown @@ -6,8 +6,10 @@ ha_category: - Utility ha_release: 0.63 ha_iot_class: Local Polling +ha_config_flow: true ha_codeowners: - '@dgomes' + - '@gjohansson-ST' ha_domain: sql ha_platforms: - sensor @@ -17,56 +19,13 @@ ha_integration_type: integration The `sql` sensor platform enables you to use values from an [SQL](https://en.wikipedia.org/wiki/SQL) database supported by the [sqlalchemy](https://www.sqlalchemy.org) library, to populate a sensor state (and attributes). This can be used to present statistics about Home Assistant sensors if used with the `recorder` integration database. It can also be used with an external data source. -## Configuration +{% include integrations/config_flow.md %} -To configure this sensor, you need to define the sensor connection variables and a list of queries to your `configuration.yaml` file. A sensor will be created for each query: +## Information -To enable it, add the following lines to your `configuration.yaml` file: +See [supported engines](/integrations/recorder/#custom-database-engines) for which you can connect with this integration. -{% raw %} -```yaml -# Example configuration.yaml -sensor: - - platform: sql - queries: - - name: Sun state - query: "SELECT * FROM states WHERE entity_id = 'sun.sun' ORDER BY state_id DESC LIMIT 1;" - column: "state" -``` -{% endraw %} - -{% configuration %} -db_url: - description: The URL which points to your database. See [supported engines](/integrations/recorder/#custom-database-engines). - required: false - default: "Defaults to the default recorder `db_url` (not the current `db_url` of recorder)." - type: string -queries: - description: List of your queries. - required: true - type: map - keys: - name: - description: The name of the sensor. - required: true - type: string - query: - description: An SQL QUERY string, should return 1 result at most. - required: true - type: string - column: - description: The field name to select. - required: true - type: string - unit_of_measurement: - description: Defines the units of measurement of the sensor, if any. - required: false - type: string - value_template: - description: Defines a template to extract a value from the payload. - required: false - type: template -{% endconfiguration %} +The SQL integration will connect to default recorder if Database URL is not specified. There is no explicit configuration required for attributes. The integration will set all additional columns returned by the query as attributes. @@ -93,17 +52,7 @@ The query will look like this: SELECT * FROM states WHERE entity_id = 'sensor.temperature_in' ORDER BY state_id DESC LIMIT 1; ``` -```yaml -# Example configuration.yaml -sensor: - - platform: sql - queries: - - name: Temperature in - query: "SELECT * FROM states WHERE entity_id = 'sensor.temperature_in' ORDER BY state_id DESC LIMIT 1;" - column: "state" -``` - -Note that the SQL sensor state corresponds to the last row of the SQL result set. +Use `state` as column for value. ### Previous state of an entity @@ -111,86 +60,42 @@ Based on previous example with temperature, the query to get the former state is ```sql SELECT * FROM (SELECT * FROM states WHERE entity_id = 'sensor.temperature_in' ORDER BY state_id DESC LIMIT 2) two_entity ORDER BY state_id ASC LIMIT 1; ``` -Thus in yaml -```yaml -# Example configuration.yaml -sensor: - - platform: sql - queries: - - name: Former_Temperature_In - query: "SELECT * FROM (SELECT state, state_id FROM states WHERE entity_id = 'sensor.temperature_in' ORDER BY state_id DESC LIMIT 2) two_entity ORDER BY state_id ASC LIMIT 1;" - column: "state" -``` +Use `state` as column for value. ### Database size #### Postgres -{% raw %} - -```yaml -sensor: - - platform: sql - db_url: postgresql://user:password@host/dbname - queries: - - name: DB size - query: "SELECT (pg_database_size('dsmrreader')/1024/1024) as db_size;" - column: "db_size" - unit_of_measurement: MB +```sql +"SELECT (pg_database_size('dsmrreader')/1024/1024) as db_size;" ``` - -{% endraw %} +Use `db_size` as column for value. #### MariaDB/MySQL Change `table_schema="hass"` to the name that you use as the database name, to ensure that your sensor will work properly. -{% raw %} - -```yaml -sensor: - - platform: sql - db_url: mysql://user:password@localhost/hass - queries: - - name: DB size - query: 'SELECT table_schema "database", Round(Sum(data_length + index_length) / 1024, 1) "value" FROM information_schema.tables WHERE table_schema="hass" GROUP BY table_schema;' - column: "value" - unit_of_measurement: kB +```sql +'SELECT table_schema "database", Round(Sum(data_length + index_length) / 1024, 1) "value" FROM information_schema.tables WHERE table_schema="hass" GROUP BY table_schema;' ``` - -{% endraw %} +Use `value` as column for value. #### SQLite -If you are using the `recorder` integration then you don't need to specify the location of the database. For all other cases, add `db_url: sqlite:////path/to/database.db`. +If you are using the `recorder` integration then you don't need to specify the location of the database. For all other cases, add `sqlite:////path/to/database.db` as Database URL. -{% raw %} - -```yaml -sensor: - - platform: sql - queries: - - name: DB Size - query: 'SELECT ROUND(page_count * page_size / 1024 / 1024, 1) as size FROM pragma_page_count(), pragma_page_size();' - column: "size" - unit_of_measurement: "MiB" +```sql +'SELECT ROUND(page_count * page_size / 1024 / 1024, 1) as size FROM pragma_page_count(), pragma_page_size();' ``` - -{% endraw %} +Use `size` as column for value. #### MS SQL -Use the same `db_url` as for the `recorder` integration. Change `DB_NAME` to the name that you use as the database name, to ensure that your sensor will work properly. Be sure `username` has enough rights to access the sys tables. +Use the same Database URL as for the `recorder` integration. Change `DB_NAME` to the name that you use as the database name, to ensure that your sensor will work properly. Be sure `username` has enough rights to access the sys tables. -{% raw %} -```yaml -sensor: - - platform: sql - db_url: "mssql+pyodbc://username:password@SERVER_IP:1433/DB_NAME?charset=utf8&driver=FreeTDS" - queries: - - name: DB size - query: "SELECT TOP 1 SUM(m.size) * 8 / 1024 as size FROM sys.master_files m INNER JOIN sys.databases d ON d.database_id=m.database_id WHERE d.name='DB_NAME';" - column: "size" - unit_of_measurement: MiB +Example Database URL: `"mssql+pyodbc://username:password@SERVER_IP:1433/DB_NAME?charset=utf8&driver=FreeTDS"` + +```sql +"SELECT TOP 1 SUM(m.size) * 8 / 1024 as size FROM sys.master_files m INNER JOIN sys.databases d ON d.database_id=m.database_id WHERE d.name='DB_NAME';" ``` -{% endraw %} +Use `size` as column for value.