QSS makes it possible to transfer state information of the Home Assistant entities simply and efficiently via InfluxDB Line Protocol into a QuestDB for long-term storage and later analysis.
What is QuestDB? QuestDB is the new kid on the block of time series optimised databases and claims to be the fastest open source time series database currently available. QuestDB offers high throughput ingestion and real-time SQL queries for applications in a wide range of use cases. It has a tiny memory footprint and combines the best of different worlds by supporting record entry via the fast and simple InfluxDB Line protocol, while offering great compatibility for common SQL queries (PostgresSQL). If you want to learn more about the possibilities of QuestDB, have a look at the documentation or this great Youtube video by Code to the Moon.
QSS itself is not a replacement for the recorder component integrated in Home Assistant, but merely offers an alternative for long-term data storage.
- β‘ Persistent, batched writes β a single, reused QuestDB connection is shared across events; rows are buffered and flushed once
max_batch_sizeis reached orflush_interval_secondshas elapsed, whichever comes first. - π Automatic retries on transient ingestion errors, so a brief network hiccup doesn't drop your data.
- π― Fine-grained filtering β include or exclude specific domains, entities, or entity glob patterns (e.g.
sensor.weather_*) from being recorded. - π Optional authenticated & SSL/TLS connections, for secured QuestDB / QuestDB Enterprise setups.
- ποΈ Configurable target table, so multiple Home Assistant instances can share the same QuestDB without colliding.
- β
Well tested with
pytest-homeassistant-custom-component, covering filtering, ingestion/retry behavior and the setup/shutdown lifecycle.
- Make sure that your QuestDB instance is up and running.
- Possible installation methods for QuestDB can be found in the 'Get started' section of the documentation.
- Apart from that, you do not need to take any further precautions at present. QSS automatically creates a table named
qssin which it stores the data.
Manual:
- Copy the
qssfolder in thecustom_componentsfolder of this repository into thecustom_componentsfolder of your Home Assistant installation.
Automatic (via HACS):
- QSS is part of the official HACS default repository collection, so it can be installed directly without adding a custom repository first: open HACS, search for "QuestDB State Storage (QSS)" and install it from there.
- Alternatively, you can still add this repository as a custom repository to your HACS installation if you want to track a specific branch or fork.
Add an entry to your Home Assistant configuration.yaml that might look like this β see the Configuration section below for all available options:
qss:
host: "192.168.178.3"
port: 9009
authentication:
ssl_check: True
kid: "your_kid"
d_key: "your_d_key"
x_key: "your_x_key"
y_key: "your_y_key"
include:
domains:
- "sensor"
entities:
- "person.john_doe"Enables the QSS integration. Only allowed once.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | Yes | β | The URL or IP address that points to your QuestDB database. |
port |
int | Yes | β | The port of the InfluxDB line protocol of your QuestDB installation. This is normally 9009 by default. |
table_name |
string | No | qss |
The name of the QuestDB table QSS should store the state data in. Useful if you want to keep multiple Home Assistant instances or environments separated within the same QuestDB. |
max_batch_size |
int | No | 500 |
QSS keeps a single, persistent connection to QuestDB open and reuses it for many events. Rows are buffered and only flushed once this many rows have accumulated (see also below). |
flush_interval_seconds |
int | No | 5 |
The maximum number of seconds buffered rows may stay unflushed before being sent to QuestDB, even if max_batch_size has not yet been reached. |
authentication |
map | No | β | Optional authentication settings β see Authentication below. |
include |
map | No | β | Entities/domains to include in recordings β see Include / Exclude below. |
exclude |
map | No | β | Entities/domains to exclude from recordings β see Include / Exclude below. |
Completely optional. Only needed if your QuestDB installation enforces authentication (requires an SSL setup, either via QuestDB Enterprise or a reverse proxy). See the QuestDB documentation for details on how to create these credentials.
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
ssl_check |
bool | No | True |
Set to False to suppress the SSL certificate check of your QuestDB installation. |
kid |
string | Yes | β | Your authentication kid. |
d_key |
string | Yes | β | Your authentication D Key. |
x_key |
string | Yes | β | Your authentication X Key. |
y_key |
string | Yes | β | Your authentication Y Key. |
Both are optional maps that control which entities QSS records. If include is set, only matching entities are recorded; exclude removes matching entities from being recorded.
| Key | Type | Required | Description |
|---|---|---|---|
domains |
List[str] | No | List of domains to include/exclude from recordings. |
entities |
List[str] | No | List of entity ids to include/exclude from recordings. |
entity_globs |
List[str] | No | List of glob patterns to include/exclude from recordings (e.g. sensor.weather_*). |
The data is stored in a QuestDB table named qss by default (configurable via table_name), which has the following structure:
| Column name: | entity_id | state | attributes | timestamps |
|---|---|---|---|---|
| Type: | symbol | string | string | timestamps |
QSS uses Poetry for dependency management and pytest (via pytest-homeassistant-custom-component) for testing. It requires Python 3.14+, matching the Python version required by current Home Assistant releases.
# Install dependencies (including dev/test dependencies)
poetry install
# Run the test suite with coverage
poetry run pytest tests/
# Run linting/formatting
poetry run pre-commit run --all-filesThe test suite covers the entity filtering logic, the QuestDB ingestion/retry behavior, and the integration setup/shutdown lifecycle without requiring a running QuestDB instance or Home Assistant installation.
- First of all, thanks to all the contributors to the great QuestDB project. Without their work, this custom component would never have been created.
- QSS was largely inspired by and based on LTSS (Long Time State Storage) by freol35241. Many thanks to freol35241 for his great work!
- QSS is not an official extension of the QuestDB project and is not directly related to it.
- No liability is accepted for any loss of data that may occur through the use of QSS. Use at your own risk!