Plugin ‚database‘ Konfiguration

Im folgenden sind etwaige Anforderungen und unterstützte Hardware beschrieben. Danach folgt die Beschreibung, wie das Plugin database konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann. [1]

Es handelt sich bei diesem Plugin um ein system Plugin.

Beschreibung

Database plugin, mit Unterstützung für SQLite 3, MySQL/MariaDB und PostgreSQL+TimescaleDB

Anforderungen

Minimum SmartHomeNG Version: 1.12.2

Konfiguration

Im folgenden ist beschrieben, wie das Plugin database konfiguriert wird. Außerdem ist im folgenden beschrieben, wie das Plugin in den Item Definitionen genutzt werden kann.

Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/plugin.yaml konfiguriert werden:

connect

Datentyp: list(str)

copy_database

Nur für SQLite3 (driver: sqlite3): Erzeugt beim Start von SmartHomeNG eine Kopie der Datenbankdatei.

Datentyp: bool

Standardwert: False

copy_database_name

Nur für SQLite3 (driver: sqlite3): Pfad/Name der Datenbank-Kopie.

Datentyp: str

count_logentries

Zeigt im Web-Interface eine zusätzliche Spalte mit der Anzahl der Datenbankeinträge je Item an.

Datentyp: bool

Standardwert: False

cycle

Wie oft (in Sekunden) gepufferte Werte in die Datenbank geschrieben werden.

Datentyp: int

Standardwert: 60

default_maxage

Ist dieser Wert größer 0, gilt er als Standard-database_maxage für Items ohne eigenes database_maxage.

Datentyp: int

Standardwert: 0

Minimalwert: 0

default_maxage_action

Standardaktion für Items mit database_maxage, die kein eigenes database_maxage_action gesetzt haben. ‚on‘ ist ein veralteter Alias für ‚duty_cycle‘.

Datentyp: str

Standardwert: delete

default_maxage_interval

Standard-Kompaktierungsintervall für Items, die kein eigenes database_maxage_interval gesetzt haben (nur relevant, wenn database_maxage_action des Items nicht ‚delete‘ ist). Angabe in Sekunden, Minuten (m) oder Stunden (h), auch kombinierbar (z.B. ‚30m‘, ‚2h30m‘). Tage müssen in Stunden angegeben werden (z.B. 7 Tage = ‚168h‘).

Datentyp: str

Standardwert: 24h

driver

Das DB-API2-Treibermodul. Akzeptiert die echten Modulnamen (‚sqlite3‘, ‚pymysql‘, ‚psycopg2‘, ‚psycopg‘) sowie entsprechende Datenbank-Namen: ‚mysql‘/‘mariadb‘, ‚postgres‘/‘postgresql‘/‘timescale‘/‘timescaledb‘.

Datentyp: str

Standardwert: sqlite3

invalid_check_cycle

Wie oft (in Sekunden) Items mit database_invalid_after geprüft werden.

Datentyp: int

Standardwert: 60

Minimalwert: 1

invalid_check_grace_time

Zusätzliche Karenzzeit (in Sekunden), die nach dem Start des Plugins gewartet wird, bevor die Prüfung des invalid_check_cycle startet.

Datentyp: int

Standardwert: 60

Minimalwert: 0

max_aggregate_intervals

Maximale Anzahl an Kompaktierungsintervallen, die pro Durchlauf und Item verarbeitet werden - begrenzt die Last auf der Datenbank bei großen Altbeständen. Gilt nur für die Plugin-seitige Kompaktierung, nicht bei timescale_native_aggregation: true.

Datentyp: int

Standardwert: 30

Minimalwert: 1

max_delete_logentries

Maximale Anzahl an Datenbankeinträgen mit database_maxage-Attribut, die in einem Durchlauf gelöscht werden - begrenzt die Last auf der Datenbank bei großen Altbeständen.

Datentyp: int

Standardwert: 20000

Minimalwert: 1000

max_reassign_logentries

Maximale Anzahl an Datenbankeinträgen, die in einem Durchlauf neu einem Item zugewiesen werden - begrenzt die Last auf der Datenbank bei großen Datenbeständen.

Datentyp: int

Standardwert: 20000

Minimalwert: 100

precision

Nachkommastellen der aus der Datenbank gelesenen Werte.

Datentyp: int

Standardwert: 2

prefix

Ein Präfix, das vor die Tabellennamen des Plugins gestellt wird - nützlich, um mit anderen Tabellen in derselben Datenbank zu koexistieren.

Datentyp: str

removeold_cycle

Wie oft (in Sekunden) auf veraltete Datenbankeinträge (database_maxage) geprüft wird. Ohne Wirkung bei timescale_native_aggregation: true.

Datentyp: int

Standardwert: 91

sqlite_wal_mode

Nur für SQLite3 (driver: sqlite3): Versetzt die Datenbankdatei in den WAL-Journal-Modus - erlaubt parallele Schreib- und Lesevorgänge. ACHTUNG: Dies ist eine Einwegentscheidung - WAL ist eine Eigenschaft der Datenbankdatei selbst, bleibt über Neustarts hinweg bestehen und wird von jeder künftigen Verbindung (auch von anderen Tools) übernommen. Diesen Parameter später wieder auf False zu setzen, macht eine bereits umgestellte Datei nicht rückgängig.

Datentyp: bool

Standardwert: False

time_precision

Nachkommastellen (für Sekunden) der aus der Datenbank gelesenen Zeitwerte.

Datentyp: int

Standardwert: 3

Minimalwert: 0

Maximalwert: 3

timescale_chunk_interval

Nur für PostgreSQL mit timescale_hypertable aktiv: Größe der Zeitpartitionen, in die die log-Tabelle aufgeteilt wird. Angabe in Sekunden, Minuten (m) oder Stunden (h), auch kombinierbar (z.B. ‚30m‘, ‚2h30m‘). Tage müssen in Stunden angegeben werden (z.B. 7 Tage = ‚168h‘). Gilt nur für neu angelegte Partitionen, bestehende werden nicht verändert.

Datentyp: str

Standardwert: 168h

timescale_compress

Nur für PostgreSQL mit timescale_hypertable aktiv: Aktiviert native spaltenbasierte Kompression der log-Tabelle. Die aktuellste Zeitpartition bleibt unkomprimiert. Diesen Parameter auf False zurückzusetzen deaktiviert nur künftige Aktivierungsversuche, hebt bereits aktive Kompression nicht auf.

Datentyp: bool

Standardwert: False

timescale_hypertable

Nur für PostgreSQL: Aktiviert die TimescaleDB-Extension und wandelt die log-Tabelle in eine Hypertable um - beschleunigt zeitbereichsbasierte Abfragen (Graphen, Statistiken) auf großen Tabellen erheblich. Setzt voraus, dass TimescaleDB auf dem PostgreSQL-Server installiert ist; falls nicht, wird eine Warnung ausgegeben und das Feature bleibt inaktiv, der Rest des Plugins funktioniert unverändert.

Datentyp: bool

Standardwert: True

timescale_native_aggregation

Nur für PostgreSQL mit timescale_hypertable aktiv: False (Standard) nutzt die bestehende Python-seitige Kompaktierung (wie bei sqlite3/MySQL). True nutzt stattdessen TimescaleDB Continuous Aggregates. Ein Wechsel von True zurück zu False ist nicht vorgesehen und kann nicht verlustfrei erfolgen.

Datentyp: bool

Standardwert: False

timescale_native_retention

Nur für PostgreSQL mit timescale_native_aggregation aktiv: Entfernt alte Rohdaten-Zeitpartitionen automatisch auf dem Datenbank-Server, statt diese vom Plugin einzeln zu löschen. Die Löschung erfolgt partitionsweise für alle Items, nicht garantiert nach Ablauf der pro Item eingestellten Zeit. ACHTUNG: Es werden ALLE Items gelöscht, nicht nur die mit eingestelltem database_maxage. Ein unbegrenztes Aufbewahren ist in diesem Modus nicht möglich. Es wird empfohlen, default_maxage > 0 und default_maxage_action != ‚delete‘ zu setzen.

Datentyp: bool

Standardwert: False

Item Attribute

Das Plugin unterstützt folgende Item Attribute, die in den Dateien im Verzeichnis ../items verwendet werden:

database

Bei ‚yes‘ oder ‚true‘ werden Wertänderungen des Items in die Datenbank geschrieben. Bei ‚init‘ wird zusätzlich beim Start von SmartHomeNG der letzte Wert des Items aus der Datenbank gelesen.

Datentyp: str

database_acl

‚rw‘ (Standard) schreibt Wertänderungen normal in die Datenbank. ‚ro‘ unterdrückt das Schreiben für dieses Item - nützlich, wenn die Datenbank für dieses Item bereits Daten aus einer anderen Quelle enthält, die nicht überschrieben werden sollen.

Datentyp: str

Standardwert: rw

database_invalid_after

Maximale Zeit ohne Änderungen oder Updates, nach der ein Item automatisch als ungültig markiert wird - sinnvoll nur bei Items mit regelmäßigen Aktualisierungen (z.B. über cycle/crontab). Angabe in Sekunden, Minuten (m) oder Stunden (h), auch kombinierbar (z.B. ‚30s‘, ‚5m‘). Erfordert das Item-Attribut ‚enforce_updates‘. Nicht mit database_acl: ro kombinierbar.

Datentyp: str

database_maxage

Maximales Alter (in Tagen) der Datenbankeinträge, die für dieses Item behalten werden. Ohne Angabe werden die Werte unbegrenzt gespeichert.

Datentyp: num

Minimalwert: 0

database_maxage_action

Aktion, die beim Erreichen von database_maxage auf ältere Datenbankeinträge angewendet wird. ‚delete‘ (Standard) löscht die Einträge ersatzlos; jeder andere Wert ersetzt sie durch einen Kompaktierungswert pro database_maxage_interval statt sie zu löschen. ‚duty_cycle‘ (nur bool-Items) berechnet den zeitgewichteten Ein-Anteil. ‚on‘ ist ein veralteter Alias für ‚duty_cycle‘, nur aus Kompatibilitätsgründen akzeptiert. Ohne eigenen Wert gilt der Plugin-Parameter default_maxage_action.

Datentyp: str

database_maxage_interval

Kompaktierungsintervall, nur relevant wenn database_maxage_action nicht ‚delete‘ ist. Angabe in Sekunden, Minuten (m) oder Stunden (h), auch kombinierbar (z.B. ‚30m‘, ‚2h30m‘). Tage müssen in Stunden angegeben werden (z.B. 7 Tage = ‚168h‘). Ohne eigenen Wert gilt der Plugin-Parameter default_maxage_interval.

Datentyp: str

database_write_on_shutdown

Schreibt den Itemwert beim Beenden von SmartHomeNG erneut in die Datenbank, auch ohne echte Änderung (Standard: True). Bei False entfällt dieses abschließende Schreiben.

Datentyp: bool

Standardwert: True

Item-Structs

Das Plugin stellt die folgenden Item-Structs zur Verfügung. Diese Informationen sind aus der plugin.yaml entnommen und möglicherweise nicht vollständig.

max

max (foo, —)
- db_max (num, —)

min

min (foo, —)
- db_min (num, —)

Logik Parameter

Das Plugin verfügt über folgende Parameter, die in der Datei ../etc/logic.yaml konfiguriert werden:

Keine Logik Parameter in den Metadaten beschrieben - Bitte in der README nachsehen (siehe Fußnote)

Plugin Functions

Das Plugin verfügt über folgende öffentliche Funktionen, die z.B. in Logiken aufgerufen werden können.

cleanup()

Räumt die Datenbank auf (löscht Item- und Log-Datenbankeinträge, die zu keinem konfigurierten Item mehr gehören). Diese Methode entfernt alle Item- und Log-Datenbankeinträge von Items, die aktuell nicht zur Protokollierung in der Datenbank konfiguriert sind. Vorsicht bei der Verwendung in einem Setup mit mehreren Plugin-Instanzen.

Die Funktion liefert kein Ergebnis

db()

Liefert das Low-Level-Datenbankobjekt.

Ergebnistyp der Funktion: foo

deleteItem(id, cur)

Löscht einen Item-Datenbankeintrag und die zugehörigen Log-Datenbankeinträge.

Die Funktion liefert kein Ergebnis

Parameter:

id

Datenbank-ID des Items, dessen Eintrag gelöscht wird.

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

deleteLog(id, time, time_start, time_end, changed, changed_start, changed_end, cur)

Löscht die Log-Datenbankeinträge für die angegebene Datenbank-ID.

Die Funktion liefert kein Ergebnis

Parameter:

id

Datenbank-ID des Items, dessen Einträge gelöscht werden.

Datentyp: int

time

Schränkt das Löschen auf die angegebene Zeit ein (optional).

Datentyp: int

time_start

Schränkt das Löschen auf die angegebene Startzeit ein (optional).

Datentyp: int

time_end

Schränkt das Löschen auf die angegebene Endzeit ein (optional).

Datentyp: int

changed

Schränkt das Löschen auf die angegebene Änderungszeit ein (optional).

Datentyp: int

changed_start

Schränkt das Löschen auf die angegebene Startzeit von Änderungen ein (optional).

Datentyp: int

changed_end

Schränkt das Löschen auf die angegebene Endzeit von Änderungen ein (optional).

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

dump(dumpfile, id, time, time_start, time_end, changed, changed_start, changed_end, cur)

Erzeugt einen Datenbank-Dump anhand der angegebenen Kriterien.

Die Funktion liefert kein Ergebnis

Parameter:

dumpfile

Dateiname, in den der Dump geschrieben wird.

Datentyp: str

id

Schränkt den Dump auf die angegebene Item-ID ein (optional).

Datentyp: int

time

Schränkt den Dump auf die angegebene Zeit ein (optional).

Datentyp: int

time_start

Schränkt den Dump auf die angegebene Startzeit ein (optional).

Datentyp: int

time_end

Schränkt den Dump auf die angegebene Endzeit ein (optional).

Datentyp: int

changed

Schränkt den Dump auf die angegebene Änderungszeit ein (optional).

Datentyp: int

changed_start

Schränkt den Dump auf die angegebene Startzeit von Änderungen ein (optional).

Datentyp: int

changed_end

Schränkt den Dump auf die angegebene Endzeit von Änderungen ein (optional).

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

id(item, create, cur)

Liefert die Datenbank-ID für das angegebene Item.

Ergebnistyp der Funktion: int

Parameter:

item

Das Item-Objekt.

Datentyp: foo

create

Falls True, wird das Item in der Datenbank angelegt, falls es dort noch nicht existiert.

Datentyp: bool

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

insertItem(name, cur)

Legt einen Item-Datenbankeintrag für die angegebene Datenbank-ID an.

Ergebnistyp der Funktion: int

Parameter:

name

Name des Items, für das ein Eintrag angelegt wird.

Datentyp: str

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

insertLog(id, time, duration, val, it, changed, cur, quality)

Legt einen Log-Datenbankeintrag für die angegebene Datenbank-ID an.

Die Funktion liefert kein Ergebnis

Parameter:

id

Datenbank-ID des Items, für das ein Eintrag angelegt wird.

Datentyp: int

time

Zeitpunkt, ab dem der Wert galt.

Datentyp: int

duration

Zeitspanne, für die der Wert galt.

Datentyp: int

val

Der Wert, der in die Datenbank geschrieben wird.

Datentyp: str

it

Der Item-Typ des Wertes (‚str‘, ‚num‘, ‚bool‘).

Datentyp: str

changed

Zeitstempel der Änderung.

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

quality

Daten-Qualitäts-Flag (Standard: QUALITY_VALID, QUALITY_NO_DATA für eine Lücken-Zeile).

Datentyp: int

readItem(id, cur)

Liest den Item-Datenbankeintrag für die angegebene Datenbank-ID. Diese Methode liest die Item-Daten einschließlich aller Felder. Ist der Parameter id ein String, wird das Item über seinen Namen ausgewählt statt über seine Datenbank-ID.

Ergebnistyp der Funktion: foo

Parameter:

id

Datenbank-ID (oder Name) des Items, dessen Eintrag gelesen wird.

Datentyp: int/str

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

readItems(cur)

Liest alle Item-Datenbankeinträge einschließlich aller Felder.

Ergebnistyp der Funktion: foo

Parameter:

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

readLog(id, time, cur)

Liest den Log-Datenbankeintrag für die angegebene Datenbank-ID.

Ergebnistyp der Funktion: foo

Parameter:

id

Datenbank-ID des Logs, dessen Eintrag gelesen wird.

Datentyp: int

time

Zeitpunkt, ab dem der Wert galt.

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

readLogs(id, time, time_start, time_end, changed, changed_start, changed_end, cur)

Liest die Log-Datenbankeinträge für die angegebene Datenbank-ID.

Ergebnistyp der Funktion: foo

Parameter:

id

Datenbank-ID des Logs, dessen Einträge gelesen werden.

Datentyp: int

time

Schränkt das Auslesen auf die angegebene Zeit ein (optional).

Datentyp: int

time_start

Schränkt das Auslesen auf die angegebene Startzeit ein (optional).

Datentyp: int

time_end

Schränkt das Auslesen auf die angegebene Endzeit ein (optional).

Datentyp: int

changed

Schränkt das Auslesen auf die angegebene Änderungszeit ein (optional).

Datentyp: int

changed_start

Schränkt das Auslesen auf die angegebene Startzeit von Änderungen ein (optional).

Datentyp: int

changed_end

Schränkt das Auslesen auf die angegebene Endzeit von Änderungen ein (optional).

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

updateItem(id, time, duration, val, it, changed, cur)

Aktualisiert den Item-Datenbankeintrag für die angegebene Datenbank-ID.

Die Funktion liefert kein Ergebnis

Parameter:

id

Datenbank-ID des Items, dessen Eintrag aktualisiert wird.

Datentyp: int

time

Zeitpunkt, ab dem der Wert galt.

Datentyp: int

duration

Zeitspanne, für die der Wert galt.

Datentyp: int

val

Der Wert, der in die Datenbank geschrieben wird.

Datentyp: str

it

Der Item-Typ des Wertes (‚str‘, ‚num‘, ‚bool‘).

Datentyp: str

changed

Zeitstempel der Änderung.

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

updateLog(id, time, duration, val, it, changed, cur, quality)

Aktualisiert den Log-Datenbankeintrag für die angegebene Datenbank-ID.

Die Funktion liefert kein Ergebnis

Parameter:

id

Datenbank-ID des Items, dessen Eintrag aktualisiert wird.

Datentyp: int

time

Zeitpunkt, ab dem der Wert galt.

Datentyp: int

duration

Zeitspanne, für die der Wert galt.

Datentyp: int

val

Der Wert, der in die Datenbank geschrieben wird.

Datentyp: str

it

Der Item-Typ des Wertes (‚str‘, ‚num‘, ‚bool‘).

Datentyp: str

changed

Zeitstempel der Änderung.

Datentyp: int

cur

Ein Datenbankcursor-Objekt, falls vorhanden (optional).

Datentyp: foo

quality

Daten-Qualitäts-Flag (Standard: QUALITY_VALID, QUALITY_NO_DATA für eine Lücken-Zeile).

Datentyp: int