Skip to content
CM000nPublic

About

QuestDB State Storage (QSS) Custom Component for Home Assistant to store entity states inside a QuestDB.

Topics

Resources

Security policy

Stars

11 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

637 Commits

Folders and files

Repository files navigation

QuestDB Logo

QuestDB State Storage (QSS)

Store your Home Assistant entity states in QuestDB β€” fast, async and HACS-ready.

GitHub release HACS default Validate Tests License

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

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.

Features

  • ⚑ Persistent, batched writes β€” a single, reused QuestDB connection is shared across events; rows are buffered and flushed once max_batch_size is reached or flush_interval_seconds has 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.

Table of Contents

Installation

Precondition

  • 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 qss in which it stores the data.

Installation of the QSS component:

Manual:

  • Copy the qss folder in the custom_components folder of this repository into the custom_components folder 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"

Configuration

qss (Required, map)

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.

Authentication

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.

Include / Exclude

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_*).

Details

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

Development

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-files

The 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.

Credits

Disclaimer

  • 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!

About

QuestDB State Storage (QSS) Custom Component for Home Assistant to store entity states inside a QuestDB.

Topics

Resources

Security policy

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages