✍️ Scribe: Long-Term History for Home Assistant (TimescaleDB)

Share your Projects! Custom Integrations
1

Hi everyone! :wave:

I’m sharing Scribe (GitHub - jonathan-gatard/scribe), a custom component to record Home Assistant history to a TimescaleDB database.

:handshake: Feedback Wanted!

I’m just starting out with this project and I’m very open to advice!

  • Is the architecture sound?
  • Are there features you’d expect from a tool like this?
  • Any tips on optimization?

I’d love to hear your thoughts! :chart_with_upwards_trend:

:baby: For Everyone (The “Why”)

If you want to keep years of sensor data without slowing down Home Assistant, Scribe is for you. It runs alongside your default recorder.

:white_check_mark: Pros:

  • Infinite History: Keep data for years without bloating your main HA database.
  • Performance: Your Home Assistant stays fast because it doesn’t have to manage massive history files.
  • Visualization: Perfect for creating beautiful dashboards in Grafana.

:x: Cons:

  • Setup Required: You need a running TimescaleDB instance (Docker or Add-on).
  • External Viewing: This data is optimized for external tools (like Grafana), not the built-in “History” tab. (Though you can use custom cards like apexcharts-card or history-explorer-card to view it in dashboards).

:nerd_face: For Advanced Users (The “How”)

Scribe is built to be a “set and forget” high-performance writer.

  • Async-First: Built on asyncpg. It writes data asynchronously and never blocks the main event loop.
  • TimescaleDB Native: Automatically manages Hypertables and Compression Policies.
    • Compression: Typical savings of 90-95%. (e.g., 50GB of raw data becomes ~2.5GB on disk).
  • Rich Context: It doesn’t just dump states. It syncs Users, Areas, Devices, and Integrations to dedicated metadata tables.
    • Example: SELECT * FROM states JOIN areas ON ...
  • Resilient: Features an in-memory buffer. If the DB is down, Scribe queues events and retries automatically.

:floppy_disk: Data Examples

Scribe stores data in a structured way that is easy to query.

States Table (states):

time entity_id state value attributes
2023-10-27 10:00:00 sensor.temp 20.5 {"unit": "C"}
2023-10-27 11:00:00 binary_sensor.switch on

Data Tables:

  • states: Records all state changes.
  • events: Records all events (if enabled).

Metadata Tables:

  • users: Syncs HA users (name, is_admin, etc.)
  • areas: Syncs areas (Living Room, Kitchen…)
  • devices: Syncs device info (Model, Manufacturer…)
  • entities: Syncs entity registry info (Platform, Domain, Name…)
  • integrations: Syncs config entries (Domain, Title…)

Keywords: Home Assistant, TimescaleDB, PostgreSQL, PSQL, History, Recorder, Long-term Storage, Grafana, Analytics, Database, Custom Component, Data Science, Big Data, SQL, Hypertables, Compression, Dashboard, Visualization, InfluxDB alternative, LTS.

1 Like