db_handler

Rust library for the Home IoT backend: primary database (SQLite), time-series history (InfluxDB 2.x), and domain services (sensors, users, keys, refresh tokens, nonces).

Features

• Primary DB: SQLite with sqlx, migrations, connection pooling
• History DB: InfluxDB 2.x client (rustls), sensor history (e.g. contact sensors)
• Domain: Sensors (typed models, contact sensors), users (bcrypt), keys, refresh tokens, nonces
• Optional: OpenAPI docs via utoipaDoc feature

Prerequisites

• Rust 1.75+ (2021 edition)
• SQLite
• InfluxDB 2.x (for history features; optional for tests via Docker)
• Dependency: db_derive — not on crates.io; use path, Git, or the Forgejo package registry (see Building).

Building

db_derive is required.

Git dependency:
In Cargo.toml, replace the path with one of:

# Default branch (e.g. main)
db_derive = { git = "https://code.bhk-itsolutions.com/homeiot/db_derive.git" }

# Pin to a tag (recommended for reproducible builds)
db_derive = { git = "https://code.bhk-itsolutions.com/homeiot/db_derive.git", tag = "v0.1.0" }

# Or pin to a specific commit
db_derive = { git = "https://code.bhk-itsolutions.com/homeiot/db_derive.git", rev = "abc1234" }

With Git, tag and rev are exact (one tag = one version). For version ranges (e.g. accept all 0.2.x), use the Forgejo package registry below.

Option C — Forgejo package registry (version ranges):
If db_derive is published on your Forgejo instance, you can use Cargo’s package registry and semver ranges.

1. One-time setup — in ~/.cargo/config.toml add (replace URL and owner if needed):

[registries.forgejo]
index = "sparse+https://code.bhk-itsolutions.com/api/packages/homeiot/cargo/"

2. In Cargo.toml, use the registry and a version requirement:

db_derive = { version = "0.2", registry = "forgejo" }

This uses Cargo semver (e.g. "0.2" ⇒ ^0.2, so any 0.2.x). For publishing db_derive to Forgejo, see Forgejo Cargo registry.

Then:

cd db_handler
cargo build --features "sensors,users,utoipaDoc"

Configuration

The application reads configuration from a JSON file. Set the path via the CONFIG_FILE environment variable (default: config.json in the current directory).

Example config (copy from config.example.json and fill in):

{
  "primary_db_url": "sqlite:data/home_iot.db",
  "history_db_url": "http://localhost:8086",
  "history_db_org": "my-org",
  "history_db_token": "your-influxdb-token"
}

• primary_db_url: SQLite connection URL (e.g. sqlite:path/to/file.db or :memory: for tests).
• history_db_url: InfluxDB 2.x URL (e.g. http://localhost:8086).
• history_db_org: InfluxDB organization name.
• history_db_token: InfluxDB API token.

Do not commit real credentials. Use config.example.json as a template and keep config.json or config.local.json local (they are in .gitignore).

Running tests

Run tests in Docker (recommended; includes InfluxDB). If Cargo.toml uses the Forgejo registry for db_derive, set a read-only token (e.g. in .env): CARGO_REGISTRIES_FORGEJO_TOKEN=your_token. See .env.example.

./scripts/test-docker.sh

See README.DOCKER.md for options (--keep, manual commands, etc.).

Troubleshooting (Docker tests): If the 4 set_history tests fail with InfluxDB error "no space left on device", Docker has run out of disk space. Free space and retry: docker system prune -a (removes unused images/containers), and/or increase the Docker Desktop virtual disk size in settings.

To run tests locally (requires SQLite and optional InfluxDB), set CONFIG_FILE to the test config and run cargo:

export CONFIG_FILE=config.test.json
cargo test --features "sensors,utoipaDoc,users"

Project layout

• src/ – Library code
  • db/ – Primary DB connection, migrations; history DB connection
  • sensors/ – Sensor models, repository, service; contact sensor and history
  • history/ – InfluxDB-backed history (sensors, keys)
  • users/, keys/, refresh_token/, nonces/ – Domain services
  • common/ – Config, helpers
• migrations/ – SQLite migrations (sqlx)
• scripts/ – Test and Docker helper scripts
• config.test.json – Test config (safe to commit; uses test token)
• config.example.json – Example config (no secrets)

Features (cargo)

• sensors – Sensor and contact sensor support
• users – User and auth-related services
• utoipaDoc – OpenAPI documentation (adds utoipa dependency)
• models – Optional model/API extras

Build with the features you need, for example:

cargo build --features "sensors,users,utoipaDoc"

License

Personal use only, non-commercial. See LICENSE.