db_handler (0.1.0)
Installation
[registries.forgejo]
index = "sparse+cargo add db_handler@0.1.0 --registry forgejoAbout this package
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
utoipaDocfeature
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.
- One-time setup — in
~/.cargo/config.tomladd (replace URL and owner if needed):
[registries.forgejo]
index = "sparse+https://code.bhk-itsolutions.com/api/packages/homeiot/cargo/"
- 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.dbor: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 codedb/– Primary DB connection, migrations; history DB connectionsensors/– Sensor models, repository, service; contact sensor and historyhistory/– InfluxDB-backed history (sensors, keys)users/,keys/,refresh_token/,nonces/– Domain servicescommon/– Config, helpers
migrations/– SQLite migrations (sqlx)scripts/– Test and Docker helper scriptsconfig.test.json– Test config (safe to commit; uses test token)config.example.json– Example config (no secrets)
Features (cargo)
sensors– Sensor and contact sensor supportusers– User and auth-related servicesutoipaDoc– OpenAPI documentation (addsutoipadependency)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.
Dependencies
| ID | Version |
|---|---|
| anyhow | ^1.0.102 |
| async-trait | ^0.1 |
| bcrypt | ^0.19.0 |
| chrono | ^0.4.44 |
| db_derive | ^0.1 |
| dotenvy | ^0.15.7 |
| env_logger | ^0.11.9 |
| futures | ^0.3.32 |
| include_dir | ^0.7 |
| influxdb2 | ^0.5 |
| log | ^0.4.29 |
| once_cell | ^1.21.3 |
| serde | ^1.0.214 |
| serde_json | ^1.0.149 |
| sqlx | ^0.8.6 |
| thiserror | ^2.0.18 |
| tokio | ^1.50.0 |
| utoipa | ^5.4.0 |
| futures | ^0.3 |