A UPS in the map: read over NUT or SNMP, alerts, shutdown order

New UPS integration (NUT or SNMP v2c, read only). Monitoring -> UPS shows charge,
runtime, load and mains voltage with history and the times mains power was lost.
Mains lost and a nearly empty battery are critical alerts; battery to be replaced
and a heavy load are warnings. The UPS is a node in the dependency map and counts
as down while on battery, so servers that go offline with it are folded under its
alert; the page lists what is on it in the order to shut it down. /metrics series
and docs added.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 21:47:31 +02:00
1 parent 3cb3e4988f
commit 232a5661ab
38 files changed
+8049 -16

No files matched your search

+37 -4
View File
@@ -23,8 +23,8 @@ what the app actually creates.
|---|---|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0053`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 62 application tables, plus drizzle's own `__drizzle_migrations`. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0054`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 64 application tables, plus drizzle's own `__drizzle_migrations`. |
**Not in the database, but beside it in the data folder:** the backups of the database itself (`backups/homelab-manager-….sqlite`, taken daily and on request; see [BACKUP.md](BACKUP.md)), and, only while a restore is waiting or has just happened, `restore-pending.sqlite` / `restore-pending.json` and `restore-result.json`.
@@ -44,7 +44,7 @@ what the app actually creates.
- Dates without a time (`secrets.expiry_date`, `domains.expires_at`) are `YYYY-MM-DD`.
- **JSON columns** are `TEXT` holding JSON; see [what's inside](#whats-stored-inside-the-json-columns).
- **Enumerations** (roles, types) are plain text — SQLite doesn't enforce the allowed values; the app does.
- **Indexes:** besides primary keys and the unique ones listed per table, a few plain indexes serve the tables that are read by range or by what they are about: `endpoint_results`, `heartbeat_pings`, `server_metrics`, `ha_readings` and `storage_samples` (by owner and time), `restore_tests`, `renewals`, `update_runs`, `patch_plan_runs`, `alert_incidents`, `incident_notes`, `alert_tickets`, `runbooks` and `status_items`. The other tables have a few thousand rows at most and need none.
- **Indexes:** besides primary keys and the unique ones listed per table, a few plain indexes serve the tables that are read by range or by what they are about: `endpoint_results`, `heartbeat_pings`, `server_metrics`, `ha_readings`, `ups_readings` and `storage_samples` (by owner and time), `restore_tests`, `renewals`, `update_runs`, `patch_plan_runs`, `alert_incidents`, `incident_notes`, `alert_tickets`, `runbooks` and `status_items`. The other tables have a few thousand rows at most and need none.
## How the tables relate
@@ -66,6 +66,8 @@ erDiagram
storage_series ||--o{ storage_samples : "cascade"
integrations ||--o{ ha_entities : "cascade"
integrations ||--o{ ha_readings : "cascade"
integrations ||--o| ups_state : "cascade"
integrations ||--o{ ups_readings : "cascade"
users ||--o{ todos : "assignee (set null)"
servers ||--o{ network_server_links : "cascade"
integration_credentials ||--o{ dns_providers : "credential (set null)"
@@ -813,6 +815,36 @@ A numeric value of a watched entity at a moment, for the chart: one at most ever
| `at` | text NOT NULL | ISO. |
| `value` | real NOT NULL | |
#### `ups_state`
How a UPS (an integration of type `ups`) is right now, one row each, replaced at every read (every minute). `integration_id` is the primary key and a foreign key with **cascade**.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | → `integrations.id`. |
| `model`, `manufacturer` | text | As the UPS says. |
| `status_text` | text NOT NULL | The UPS's own words (`OL CHRG`, `on battery, battery normal`). |
| `on_battery`, `low_battery`, `replace_battery`, `overload` | bool NOT NULL, default 0 | Mains power lost; battery nearly empty; battery to be replaced; overloaded. |
| `charge`, `load_percent` | real | Percent. |
| `runtime_seconds` | integer | How long the battery would last at the present load. |
| `input_voltage`, `output_voltage` | real | Volts. |
| `on_battery_since` | text | ISO; when mains power was lost, kept until it is back. |
| `updated_at` | text NOT NULL | ISO; the last read that worked. |
How the last read went (and when it last worked) is in `settings` under the internal key `upsSync`, like the Home Assistant sync's.
#### `ups_readings`
A UPS at a moment, for the charts: one every five minutes, and every minute while it runs on battery (or when that changes), deleted after 35 days. `integration_id` is a foreign key with **cascade**; (`integration_id`, `at`) is indexed.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `at` | text NOT NULL | ISO. |
| `charge`, `load_percent`, `input_voltage` | real | |
| `runtime_seconds` | integer | |
| `on_battery` | bool NOT NULL, default 0 | |
#### `alert_rules`
Limits of the administrator's own (Monitoring → Alert rules), judged for the servers they cover on the health pass; what they find is ordinary health conditions keyed `rule:<id>:server:<server>[:<disk>]`.
@@ -1130,7 +1162,7 @@ settings, and aren't part of the app's settings object:
|---|---|
| a **server** | Its `scheduled_tasks`, `server_links`, `server_ports`, `server_metrics`, `server_metrics_rollup`, `update_runs` and `network_server_links` are deleted with it. Port forwards that pointed at it stay, with `server_id` cleared. Things that refer to it by id only (notes, to-do items, endpoint checks, heartbeats, alert rules, dependencies, runbooks, maintenance windows) stay, pointing at nothing — see below. |
| a **DNS provider** | Its cached zones and records are deleted. |
| an **integration** | What was read from it is deleted with it: UniFi devices, networks and server links, Home Assistant watched entities and readings, and the history of its storage pools (`storage_series`, `storage_samples`). |
| an **integration** | What was read from it is deleted with it: UniFi devices, networks and server links, Home Assistant watched entities and readings, a UPS's state and readings, and the history of its storage pools (`storage_series`, `storage_samples`). |
| an **endpoint check**, a **heartbeat**, an **incident**, a **patch plan**, a **share link**, an **event webhook** | Their results and summaries (`endpoint_results`, `_hourly`, `_daily`), pings, notes, runs, status-page items and delivery log (`webhook_deliveries`). |
| an **integration** or **DNS provider** | The credential row it used is deleted by the app (not by the database). |
| an **integration** used for alert tickets | `alert_tickets.integration_id` is cleared; the history stays. |
@@ -1187,6 +1219,7 @@ are deleted), and `notification_queue` is emptied each time the quiet-hours dige
| `endpoint_hourly`, `endpoint_daily` | 120 days, and 800 days |
| `storage_samples` | 400 days (a pool not reported for 30 days is deleted with its readings) |
| `ha_readings` | 35 days |
| `ups_readings` | 35 days |
| `heartbeat_pings` | 14 days |
| `alert_incidents`, `incident_notes` | 400 days after the incident resolved |
| `webhook_deliveries` | the newest 100 per webhook, and 14 days |