Files
Homelab-manager/DATABASE.md
T
bobbanandClaude Sonnet 5.5 551eb1597a AdGuard Home, Grafana, Docker image age, foldable server page cards
New integration kinds adguard (status, statistics, filter lists and a real DNS question
over UDP; alerts for DNS down/not running, protection left off, stale lists) and grafana
(alert rules firing or failing, data-source health). Optional warning for running Docker
images built more than N days ago (off by default). A server's overview cards can be
folded and arranged, kept per user. Migrations 0075-0077; docs, metrics and tests included.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-27 22:13:03 +01:00

1642 lines
104 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Database schema
Homelab Manager keeps its data in one SQLite file, accessed through
[drizzle-orm](https://orm.drizzle.team) and the libSQL client. The schema is
defined in one place — [`server/src/db/schema.ts`](server/src/db/schema.ts) —
and this document describes it. It was checked against a fresh database built
from the migrations, so the tables, columns, foreign keys and indexes below are
what the app actually creates.
- [The basics](#the-basics)
- [How the tables relate](#how-the-tables-relate)
- [Tables](#tables)
- [What's stored inside the JSON columns](#whats-stored-inside-the-json-columns)
- [Settings keys](#settings-keys)
- [What happens on delete](#what-happens-on-delete)
- [The Proxmox link's foreign key](#the-proxmox-links-foreign-key)
- [Retention and backups](#retention-and-backups)
- [Changing the schema](#changing-the-schema)
## The basics
| | |
|---|---|
| **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` … `0077`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 87 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`.
**Not in the database:**
- **Login sessions** are files in `SESSION_DIR` (default `../data/sessions`), not rows.
- **The encryption key** for integration credentials (`CREDENTIALS_ENCRYPTION_KEY`) and the session secret live in the environment, never in the file.
- **Agent tokens** are never stored: only a SHA-256 hash and a short prefix of each (`servers.api_token_hash`, `api_token_prefix`). The token itself is shown once, when the server is registered.
### Conventions
- **Primary keys** are `INTEGER PRIMARY KEY AUTOINCREMENT` named `id` — except `settings`, which uses its text `key`.
- **Booleans** are `INTEGER` 0/1 (shown as `bool` below).
- **Timestamps are text, in two formats**, so read them with care:
- Columns the database fills in itself (`created_at`, and most `updated_at`) use SQLite's `current_timestamp`: `2026-10-03 14:05:09`, **UTC, with no zone marker**. Treat it as UTC, not local time.
- Columns the app fills in (`last_seen_at`, `last_login_at`, `synced_at`, `last_checked_at`, …) use ISO 8601: `2026-10-03T14:05:09.123Z`.
- 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`, `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
```mermaid
erDiagram
users ||--o{ audit_log : "actor (set null)"
users ||--o{ push_subscriptions : "cascade"
endpoint_checks ||--o{ endpoint_results : "cascade"
heartbeats ||--o{ heartbeat_pings : "cascade"
integration_credentials ||--o{ integrations : "credential (set null)"
users ||--o{ api_tokens : "cascade"
servers ||--o{ server_metrics_rollup : "cascade"
endpoint_checks ||--o{ endpoint_hourly : "cascade"
integrations ||--o{ network_devices : "cascade"
integrations ||--o{ network_segments : "cascade"
integrations ||--o{ network_server_links : "cascade"
integrations ||--o{ ha_watched : "cascade"
integrations ||--o{ storage_series : "cascade"
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"
integrations ||--o| jellyfin_state : "cascade"
integrations ||--o| authentik_state : "cascade"
integrations ||--o| prometheus_state : "cascade"
integrations ||--o| immich_state : "cascade"
integrations ||--o| nextcloud_state : "cascade"
integrations ||--o{ dockhand_vulnerabilities : "cascade"
integrations ||--o| hetzner_state : "cascade"
integrations ||--o| fragnet_state : "cascade"
integrations ||--o| arr_state : "cascade"
integrations ||--o| adguard_state : "cascade"
integrations ||--o| grafana_state : "cascade"
integrations ||--o{ speedtest_results : "cascade"
integrations ||--o| netbox_state : "cascade"
integrations ||--o| n8n_state : "cascade"
integrations ||--o| paperless_state : "cascade"
integrations ||--o{ jellyfin_readings : "cascade"
users ||--o{ todos : "assignee (set null)"
servers ||--o{ note_photos : "cascade"
network_devices ||--o{ note_photos : "cascade"
servers ||--o{ network_server_links : "cascade"
integration_credentials ||--o{ dns_providers : "credential (set null)"
dns_providers ||--o{ dns_zones_cache : "cascade"
dns_providers ||--o{ dns_records_cache : "cascade"
servers ||--o{ scheduled_tasks : "cascade"
servers ||--o{ server_links : "cascade"
servers ||--o{ server_metrics : "cascade"
servers ||--o{ server_ports : "cascade"
servers ||--o{ port_forwards : "optional (set null)"
integrations ||--o{ servers : "proxmox link (app clears it)"
integrations ||--o{ alert_tickets : "osTicket used (set null)"
share_links ||--o{ status_items : "cascade"
users ||--o{ alert_acks : "assignee (set null)"
alert_incidents ||--o{ incident_notes : "cascade"
servers ||--o{ update_runs : "cascade"
patch_plans ||--o{ patch_plan_runs : "cascade"
endpoint_checks ||--o{ endpoint_daily : "cascade"
event_webhooks ||--o{ webhook_deliveries : "cascade"
```
These 22 tables are without a foreign key to another table, and — but for `integration_credentials`, which `integrations` and `dns_providers` point at — with none from another table to them; where they refer to something else it is by id or name, see
[soft references](#soft-references-not-foreign-keys): `settings`, `secrets`, `ipam_entries`, `domains`, `diag_log`, `notification_queue`, `consistency_ignores`, `tag_definitions`,
`maintenance_windows`, `maintenance_aliases`, `maintenance_schedules`, `metrics_tokens`, `restore_tests`, `dependencies`, `runbooks`, `renewals`, `assets`, `notes`,
`alert_rules`, `alert_snoozes`, `alert_kind_runbooks` and `integration_credentials`.
## Tables
Grouped by what they're for. "Null" in the notes means the column allows NULL;
everything not marked **NOT NULL** may be empty.
### People and activity
#### `users`
Everyone who has signed in through Authentik. The first one becomes admin.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `oidc_sub` | text NOT NULL, **unique** | The user's stable ID from Authentik (`sub` claim). This is what a session is matched against. |
| `email`, `name` | text | From the sign-in; may be empty. |
| `role` | text NOT NULL, default `viewer` | `admin` \| `operator` \| `viewer`. |
| `created_at` | text NOT NULL | SQLite UTC. |
| `last_login_at` | text | ISO. |
| `favorites` | text | JSON array of the page paths this person pinned to the top of their menu (`["/servers","/alerts"]`), up to 24. A path may carry a short query for a saved view of a page (`"/servers?status=offline"`). Follows them to any browser. |
| `picture_url` | text | The `picture` claim the identity provider gave at the last sign-in. Only an address; nothing is fetched from it unless Settings → Sign-in → Profile pictures allows it (and then only Gravatar or the provider's own host). Pictures themselves are kept in the server's memory for a day, not in the database. |
| `dashboard_layout` | text | JSON object `{"hidden":["Gitea"],"order":{"Secrets":0,"DNS":1}}`: the dashboard cards this person hid and the order of the rest (lower first; a card with no entry goes last). Null = the default layout. Follows them to any browser. |
| `server_page_layout` | text | JSON object `{"folded":["admin-links"],"order":{"notes":10}}`: the cards of a server's overview page this person folded and the order of the blocks (lower first). The same for every server. Null is the page as drawn. |
| `groups` | text | JSON array of the groups the identity provider reported at this person's last sign-in (null until they have signed in with groups available) — shown on the Users page, and what "roles from groups" works from. |
| `last_looked_at` | text | ISO time this person last pressed "Got it" on the dashboard's "Since you last looked" card; the next summary starts there (null = never: the last day is shown). |
#### `audit_log`
Who changed what. Written by the app on every change (see
[ROLES.md](ROLES.md) for who can read it).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, and `agent_updated` when a server's agent reports a higher version than before, written as `system` and shown on a server's Activity card), `integration` (including the health check's `went_failing` / `recovered` for a kind of service, with `target_type` `integration_type` and the service type as `target_id`, which the dashboard summary and the uptime ribbons read), `dns`, `settings` (including `agent_auto_update`), `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket` (`close_ticket`, `close_ticket_failed`, `test_close` — never a password), `dependency` (`create`, `delete` — what needs what), `endpoint` (`create`, `update`, `delete`), `restore_test` (`record`, `delete`), `push` (`subscribe`, `unsubscribe` — a browser added or removed, never its address or keys), `share_link` (a link made or removed, and `update_status_page` when what a status page shows is changed — never the secret), `runbook`, `note` (`save`, `delete`, `photo_add`, `photo_delete` — never the picture), `alert` (`ack`, `unack`, `snooze`, `unsnooze`, `close`, `reopen`, and `bulk_snooze` / `bulk_unsnooze` / `bulk_close` / `bulk_reopen` for several at once — with the alert's id; on the thing it is about, so they show on a server's Activity card), `incident` (`note`, `note_removed`), `duplicati` (`create_source`, `update_source`, `delete_source`, `update_backup`, `forget_backup`), `db_backup` (`create`, `upload`, `download`, `delete`, `restore_staged`, `restore_cancelled`, `settings`), `away` (`start`, `end` — with `automatic: true` when its time ran out), `update_run` (`start`, `finished`, `failed`, `cancelled` — shown on the server's Activity card), `inventory`, `metrics_token` and `webhook` (made, changed or removed — never a secret or an address). `user` also records `role_from_groups` when a sign-in changed someone's role. |
| `action` | text NOT NULL | `create`, `update`, `delete`, `start`, `stop`, … — free text. |
| `target_type`, `target_id` | text | What it happened to. `target_id` is text so it can hold any kind of ID; there's no foreign key. |
| `detail` | text | JSON, free-form context (what changed, names, counts). Secrets are never put here. |
| `created_at` | text NOT NULL | SQLite UTC. |
#### `diag_log`
One row per outbound call to an integration or DNS provider — the source of
the Diagnostic Log page and of the "integration down" alert.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `source` | text NOT NULL | The integration/provider type, e.g. `proxmox`, `cloudflare`. |
| `operation` | text NOT NULL | The adapter method, e.g. `listZones`. |
| `ok` | bool NOT NULL | |
| `latency_ms` | integer NOT NULL | |
| `error` | text | Message when `ok` is false. |
| `created_at` | text NOT NULL | SQLite UTC. |
#### `notification_queue`
Notifications held back during quiet hours, delivered as one digest and then
cleared.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `title`, `message` | text NOT NULL | |
| `audience` | text | JSON of who it was for (`channels`, `pushIds`, `email`) when a routing rule or an escalation picked them; null = everyone. The digest is sent to each audience separately. |
| `created_at` | text NOT NULL | SQLite UTC. |
#### `maintenance_windows`
While a window is open, alerts about its target are silenced. An end time is
required, so a forgotten window can't silence real problems forever.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `target_type` | text NOT NULL | `server` \| `integration` \| `dns_provider` \| `device`. |
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; a window whose target was deleted is simply ignored. |
| `reason` | text | |
| `started_at`, `ends_at` | text NOT NULL | ISO. |
| `created_by` | text | Name of the person who opened it. `Uptime Kuma sync` for mirrored ones. |
| `source` | text | `kuma:<integration id>:<maintenance id>` on windows mirrored from Uptime Kuma's schedule, so a later sync can find them again; `schedule:<schedule id>:<date>` on windows made from a recurring schedule (so one is made once, even if it was cancelled); NULL for ones started by hand. A window whose `started_at` is still in the future is *scheduled*: it silences nothing until it begins. A scheduled one that is cancelled has `ends_at` set equal to `started_at`. |
#### `maintenance_schedules`
A maintenance that repeats ("Sundays 02:00–04:00 on these servers"). It only says when:
the windows that silence alerts are ordinary `maintenance_windows` rows made a week
ahead and marked `schedule:<id>:<date>`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | e.g. "Patch night". |
| `reason` | text | |
| `targets` | text NOT NULL | JSON `[{"type":"server","id":3}, …]`. Polymorphic like `maintenance_windows`, so no foreign key; a deleted target is skipped. |
| `days` | text NOT NULL | JSON array of weekdays, 0 = Sunday … 6 = Saturday. |
| `start_time` | text NOT NULL | `HH:MM` on the clock of `timezone`. |
| `duration_minutes` | integer NOT NULL | |
| `timezone` | text NOT NULL | IANA name, so 02:00 stays 02:00 across summer and winter time. |
| `enabled` | bool NOT NULL, default 1 | Off makes no windows and takes back those that haven't begun. |
| `created_by` | text | |
| `created_at` | text NOT NULL | |
#### `maintenance_aliases`
An address that Uptime Kuma's monitors use for something this app knows by another address, so the Uptime Kuma
maintenance sync can find it. Added on the Maintenance page.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `address` | text NOT NULL | A bare lowercase host: a name or an IP. |
| `target_type` | text NOT NULL | `server` | `integration` | `dns_provider`. |
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; an alias whose target was deleted is ignored. |
| `created_at` | text NOT NULL | |
Unique on (`address`, `target_type`, `target_id`).
### Servers
#### `servers`
A machine that reports in through the agent (or is registered by hand), plus
what it last reported.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | Not unique. |
| `hostname` | text | |
| `os_type` | text NOT NULL, default `linux` | |
| `description` | text | |
| `api_token_hash` | text NOT NULL | SHA-256 of the agent's token. |
| `api_token_prefix` | text NOT NULL | First characters of the token, to tell tokens apart in the UI. |
| `created_at` | text NOT NULL | SQLite UTC. |
| `last_seen_at` | text | ISO; when the agent last reported. Drives "server offline". |
| `ip_addresses` | text | JSON `string[]`. Agent-reported. |
| `cpu_model` | text | Agent-reported. |
| `cpu_cores` | integer | |
| `cpu_load_percent` | real | Load average ÷ cores × 100 — an approximation, not instantaneous usage. |
| `mem_total_bytes`, `mem_used_bytes` | integer | |
| `disks` | text | JSON, see below. Agent-reported. |
| `listening_ports` | text | JSON, see below. What the agent sees bound on the host. |
| `port_baseline` | text | JSON array like `["tcp:22","tcp:443"]`: what the host was listening on when its agent first said so. A TCP port listening later that is not in it, and not noted on the Ports card, is a "new port" alert. Null until the first report that carries ports; never changed after. |
| `last_port_scan` | text | JSON summary of the latest network scan *from this app*. |
| `tags` | text | JSON `string[]` of normalised tag names. |
| `proxmox_integration_id` | integer → `integrations.id` | The database has no `ON DELETE` rule here; the app clears the link itself — see [below](#the-proxmox-links-foreign-key). |
| `proxmox_node` | text | |
| `proxmox_guest_type` | text | `qemu` \| `lxc`. |
| `proxmox_vmid` | integer | The four `proxmox_*` columns are set together or cleared together (enforced by the API), by an admin — never by the agent. |
| `hide_proxmox_link` | bool NOT NULL, default 0 | Hides the "Proxmox link" card for servers that aren't Proxmox guests. Ignored while the server is actually linked. |
| `parent_server_id` | integer | The server this one runs on, set by an admin. **Not a foreign key** (a removed host's servers are cleared by the app). Null = work it out: a server linked to a Proxmox guest runs on the one server named after that guest's node. When the parent is down, this server's offline alert is folded under it. |
| `no_parent` | bool NOT NULL, default 0 | An admin said this server runs on nothing: no link, and no guess from its Proxmox node. Choosing a server by hand, or going back to automatic, clears it. |
| `pending_updates` | text | JSON `{"manager":"apt","count":5,"security":2,"rebootRequired":false,"reportedAt":"…"}` from the agent; null until it has said. `security` is null when the package manager can't tell. |
| `updates_pending_since` | text | ISO; when updates were first seen waiting (and none were before). Null when none are waiting. |
| `thresholds` | text | This server's own alert limits as JSON: `{"serverOfflineMinutes":…,"diskUsagePercent":…,"diskForecastDays":…,"backupStaleHours":…,"mounts":{"/data":{"percent":95,"ignore":true}},"ignoreServices":["gupdate*"]}`. `ignoreServices` are services never counted as failed here (names or patterns with `*`, up to 30). Anything left out follows Settings; null when it follows Settings entirely. Ranges are checked on the way in (offline 15–10080 min, disk 50–99 %, forecast 0–90 days, backup 0–2160 h; 0 means off). |
| `host_health` | text | JSON `{"failedUnits":[{unit,description}],"smart":[{device,model,healthy,temperatureC,wearPercent}],"zfs":[{name,health,capacityPercent}],"reportedAt":"…"}`. Each part is present only if the agent reported it, and a report that leaves one out leaves it as it was. Null until an agent says anything. Judged by the health check and shown on the server's page. |
| `hw_manufacturer`, `hw_model`, `hw_serial` | text | What the machine is, as its firmware says (the agent reports it; placeholders like "To Be Filled By O.E.M." are left out). Each is replaced only when a report has a value, so an agent that can't tell doesn't wipe what it said. Used to fill in the inventory. |
| `agent_diagnostics` | text | JSON `{"items":[{check,status,reason?,detail?}],"reportedAt":"…"}`: what the agent says it could not collect (`status` is `unavailable` or `failed`). Replaced by each report that carries the list (an empty list means nothing was missed) and kept when a report doesn't. Turned into words and fixes by the server; never sent to the browser as it is. |
| `os_id`, `os_name`, `os_version` | text | The operating system the agent reports: `os_id` is lower case (`ubuntu`, `debian`, `proxmox-ve`, `windows`…), `os_name` is what to show, `os_version` the release (a Windows build number on Windows). Replaced only by a report that says; null until then. The end-of-life dates are not stored: they are a table in the app. |
| `agent_version` | integer | Which version of the agent script runs on it, as the agent says in each report. Null until it says; an agent that predates the number counts as version 1. Compared with the scripts the app serves to say which agents are behind. |
#### `scheduled_tasks`
Cron jobs, systemd timers and Windows tasks the agent found on a server, plus
tasks added by hand.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `schedule_type` | text NOT NULL | `cron` \| `systemd_timer` \| `windows_task` from agents; manual tasks may use others (`docker`, `backup`, `update`, `n8n_workflow`, `manual`). |
| `origin` | text NOT NULL, default `agent` | `agent` \| `manual`. Manual rows are never touched by agent sync. |
| `name` | text NOT NULL | |
| `command`, `schedule_expression`, `source` | text | |
| `enabled` | bool NOT NULL, default 1 | |
| `next_run_at` | text | |
| `raw_metadata` | text | JSON as the agent reported it. |
| `is_stale` | bool NOT NULL, default 0 | Set when the agent stops reporting the task. |
| `first_seen_at`, `last_seen_at` | text NOT NULL | SQLite UTC at first insert; later updates are written by the app. |
#### `server_links`
Admin-page bookmarks for a server (Dockge, Webmin, Cockpit, …). Shown on the
server's page and summarised under Reference → Admin Links.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `label`, `url` | text NOT NULL | |
| `created_at` | text NOT NULL | SQLite UTC. |
#### `server_metrics`
A short history of each agent-reported server's load, memory and disk use, in
percent, for the Trends card on its page. At most one sample per server every
ten minutes however often its agent reports, kept for 35 days (older rows are
removed whenever a new sample is stored).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `metric` | text NOT NULL | `cpu`, `mem`, or `disk:<mount point>` (e.g. `disk:/data`). |
| `value` | real NOT NULL | Percent, 0–100, one decimal. |
| `recorded_at` | text NOT NULL | ISO. |
#### `server_metrics_rollup`
The same figures kept coarser and longer, so charts reach back a year: one row per server, figure and hour (`grain` `h`, kept 120 days) or day (`d`, kept 800 days). `at` is the start of the hour or day (ISO); `sum` and `n` give the average (and are added to as
samples arrive), `min` and `max` the lowest and highest. Written with each sample (see `server_metrics`); built once from the samples already kept when it was added (internal flag `metricsRollupBackfilled`). Primary key (`server_id`, `metric`, `grain`, `at`); deleted with its server.
A chart over up to 35 days is drawn from the samples, up to 120 from the hours, longer from the days.
Index **`server_metrics_lookup_idx`** on (`server_id`, `metric`, `recorded_at`).
#### `server_ports`
A port on one server that's been seen open by a scan, or that someone wrote a
note about. Rows exist only while they carry information. What the *agent*
sees is stored on the server row instead (`servers.listening_ports`).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `port` | integer NOT NULL | |
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
| `label`, `comment` | text | |
| `open` | bool NOT NULL, default 0 | True when the last scan connected to it. |
| `last_seen_open_at` | text | |
| `updated_at` | text NOT NULL | |
Unique index **`server_ports_unique`** on (`server_id`, `port`, `protocol`).
#### `port_forwards`
Manually recorded port openings on something this app doesn't monitor — a
router's port forward, an edge firewall rule, a cloud security group. It
records them; it can't check or change them.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `label` | text NOT NULL | |
| `external_port` | integer NOT NULL | |
| `protocol` | text NOT NULL, default `tcp` | `tcp` \| `udp`. |
| `server_id` | integer → `servers.id`, **set null** | Optional: the tracked server it points at. |
| `destination` | text | Anything else — a bare IP, an untracked device — or detail alongside `server_id`. |
| `internal_port` | integer | When NAT changes the port. |
| `source` | text | Free text: where the rule lives ("Home router", "OPNsense WAN rule"). |
| `comment` | text | |
| `created_at`, `updated_at` | text NOT NULL | |
### Integrations and credentials
#### `integrations`
A connected system: Proxmox, Synology, Semaphore, Tailscale, Gitea, Dockhand,
Uptime Kuma, phpIPAM, Proxmox Backup Server, osTicket.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `type` | text NOT NULL | `proxmox` \| `synology` \| `semaphore` \| `tailscale` \| `gitea` \| `dockhand` \| `uptimekuma` \| `phpipam` \| `pbs` \| `osticket`. |
| `name` | text NOT NULL | |
| `base_url` | text NOT NULL | For osTicket (a direct database connection) this holds the database host. |
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
| `config` | text | JSON of the *non-secret* settings, see below. |
| `enabled` | bool NOT NULL, default 1 | |
| `created_at` | text NOT NULL | |
#### `integration_credentials`
The secret half of an integration or DNS provider, encrypted at rest.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | `"<type>:<name>"`, for recognising a row when looking at the file. |
| `encrypted_secret` | text NOT NULL | `iv:authTag:ciphertext`, each in hex — AES-256-GCM with `CREDENTIALS_ENCRYPTION_KEY`. The plaintext is a JSON object of the secret fields (an API token, a password). Without the same key it can't be read. |
| `created_at` | text NOT NULL | |
The notification channels' credentials aren't in this table; they're encrypted in place in `settings` — see [Retention and backups](#retention-and-backups).
### DNS
#### `dns_providers`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_type` | text NOT NULL | `cloudflare` \| `loopia` \| `pihole` \| `azure` \| `cpanel` \| `technitium`. |
| `name` | text NOT NULL | |
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
| `config` | text | JSON, non-secret provider config (base URL, zone list, …). |
| `enabled` | bool NOT NULL, default 1 | |
| `created_at` | text NOT NULL | |
#### `dns_zones_cache` and `dns_records_cache`
Local copies of what the providers returned at the last sync, so pages load
without calling every provider. The providers remain the source of truth.
`dns_zones_cache`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
| `zone_id` | text NOT NULL | The provider's own identifier for the zone. |
| `zone_name` | text NOT NULL | |
| `synced_at` | text | ISO. |
Unique index **`dns_zones_cache_provider_zone_idx`** on (`provider_id`, `zone_id`).
`dns_records_cache`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
| `zone_id` | text NOT NULL | The provider's zone identifier — matches `dns_zones_cache.zone_id` for the same provider, but is **not a foreign key**. |
| `record_id` | text NOT NULL | The provider's own record identifier. |
| `type` | text NOT NULL | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, … |
| `name`, `content` | text NOT NULL | |
| `ttl`, `priority` | integer | |
| `proxied` | bool | Cloudflare only. |
### Address and name tracking
#### `ipam_entries`
IP addresses with a label and notes, entered by hand or synced.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `ip_address` | text NOT NULL, **unique** | |
| `label`, `vendor`, `location`, `notes` | text | |
| `source` | text | Null = typed in by hand; otherwise the sync that created it: `tailscale`, `proxmox` or `phpipam`. A sync only updates rows it created itself and never overwrites a manual one. |
| `created_at`, `updated_at` | text NOT NULL | |
#### `domains`
Registered domains whose expiry is tracked.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL, **unique** | The registrable domain, lowercase ASCII. |
| `origin` | text NOT NULL, default `manual` | `manual` (typed in) or `zone` (created from a synced DNS zone, removed again when the zone goes away). |
| `expires_at` | text | `YYYY-MM-DD`, as the registry reports it. Null for registries that don't publish one. |
| `registrar` | text | |
| `lookup_source` | text | `rdap` \| `whois`. |
| `last_checked_at` | text | Last attempt. |
| `last_checked_ok_at` | text | Last *successful* attempt. |
| `last_check_error` | text | |
| `created_at` | text NOT NULL | |
#### `secrets`
The expiry tracker for API tokens, certificates, passwords and the like. It
tracks *when* something expires; it does not store the secret itself.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `type` | text NOT NULL, default `generic` | `api_token` \| `ssl_certificate` \| `password` \| `generic`. |
| `description`, `notes` | text | |
| `expiry_date` | text | `YYYY-MM-DD`. NULL = never expires (no status, no alert). For a certificate with a host to check, overwritten from the live certificate, and never NULL. |
| `warn_days` | integer NOT NULL, default 30 | How long before expiry to start reminding. |
| `check_host`, `check_port` | text / integer | Certificates only: read the expiry from the live certificate at this host:port. |
| `last_checked_at`, `last_check_error` | text | Result of the last live check. |
| `created_at`, `updated_at` | text NOT NULL | |
### Housekeeping
#### `settings`
Key/value store for app settings. One row per settings section (the value is
JSON) plus a few internal bookkeeping rows. Details under
[Settings keys](#settings-keys).
| Column | Type | Notes |
|---|---|---|
| `key` | text PK | |
| `value` | text NOT NULL | JSON (or a plain date/time for internal flags). |
| `updated_at` | text NOT NULL | |
Internal flag `unifiSync`: a JSON object keyed by integration id, `{ at (ISO — the last *successful* read), ok, error, sites, mode, devices, networks, ssids }`. A controller whose `at` is older than twenty minutes is not judged for offline devices.
Internal flag `homeAssistantSync`: a JSON object keyed by integration id, `{ at (ISO — the last *successful* read), ok, error, entities }`. A Home Assistant whose `at` is older than twenty minutes is not judged.
Internal flag `dependencySuggestionsDismissed`: a JSON array of the suggestion keys (`integration:3>server:1`) somebody said *Not that* to.
Setting `healthChecks.osSupportWarnDays` (default 90, 0–365): how many days before an operating system's end of support it is a warning.
Internal flag `flapState`: a JSON object keyed by alert key, `{ raises: number[] (epoch ms of raises in the last hour), flapping: boolean, since, lastEvent, message }`. It is what lets a restart remember which alerts are being held as flapping; entries are dropped once an alert has been calm for an hour.
#### `tag_definitions`
Tags themselves live on the servers that carry them (`servers.tags`). A row
here adds what a server can't: a tag that exists before anything uses it, and a
chosen colour. A tag with no row is simply one in use with an automatic colour.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL, **unique** | Normalised. |
| `color` | text | `#rrggbb`, or null for automatic. |
| `created_at` | text NOT NULL | |
#### `consistency_ignores`
Consistency findings someone looked at and decided are fine.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `key` | text NOT NULL, **unique** | The finding's stable key, so it stays ignored across runs. |
| `title` | text NOT NULL | What the finding said when it was ignored, so the list still reads sensibly after it's gone. |
| `reason`, `created_by` | text | |
| `created_at` | text NOT NULL | |
#### `alert_tickets`
What the "open an osTicket ticket for an alert" feature remembers about each problem it has seen, so one problem opens one ticket however many
checks see it. A row is one *occurrence*: when an alert clears and later returns for good, that is a new row.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `alert_key` | text NOT NULL, indexed | The alert's id as the Alerts page shows it (e.g. `disk:server:3:/`). Not a foreign key — alerts aren't stored. |
| `status` | text NOT NULL | `pending` (seen, not yet in enough checks in a row), `open` (a ticket was opened), `baseline` (already there when the feature was switched on, left alone). |
| `seen_count` | integer NOT NULL, default 1 | Checks in a row it has been seen while pending. |
| `integration_id` | integer → `integrations.id`, **set null** | The osTicket integration the ticket went to. |
| `ticket_number` | text | osTicket's own number; null unless `open`. |
| `grouped` | bool NOT NULL, default 0 | Part of a summary ticket that covers several alerts (they share a number). |
| `severity`, `message` | text NOT NULL | What the alert said when it was recorded. |
| `first_seen_at`, `last_seen_at` | text NOT NULL | ISO. |
| `ticketed_at` | text | ISO; when the ticket was opened. |
| `cleared_at` | text | ISO; null while the alert is still active. Rows cleared more than 180 days ago are deleted. |
| `ticket_closed_at` | text | ISO; when this app closed the ticket in osTicket (or found it already closed when asked to). Null otherwise. |
| `ticket_closed_by` | text | Who asked, as a name. |
#### `alert_acks`
"I'm on it" for one alert. **One row per alert id.**
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `alert_key` | text NOT NULL, unique | The alert's stable id (e.g. `offline:offline:server:3`), the same key the Alerts page uses; **not a foreign key**. |
| `note` | text NOT NULL | Up to 500 characters; may be empty. |
| `assignee_user_id` | integer | → `users.id`, set to null if the user is removed. |
| `assignee_name` | text | The name as it was when handed over, so it still reads if the user is removed. |
| `acked_by` | text NOT NULL | |
| `acked_at` | text NOT NULL | ISO. |
| `until` | text | ISO; when it runs out. Null means until the alert is gone. |
| `last_seen_at` | text NOT NULL | ISO; the last time the alert was there. A row whose alert has been gone for 30 minutes is deleted. |
#### `alert_incidents`
One time an alert was raised and later went away. When the same alert comes back it is a new row. Information-only alerts are not recorded.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `alert_key` | text NOT NULL | The alert's id (indexed). Not a foreign key. |
| `severity`, `peak_severity` | text NOT NULL | As it is now (or was at the end), and the worst it got to. |
| `category`, `source`, `message`, `link` | text | As the Alerts page showed them; `message` is the latest wording. |
| `target_type`, `target_id`, `target_name` | text, integer, text | The server, integration or DNS provider it was about, when there is one (indexed). A plain reference, **not a foreign key**. |
| `caused_by` | text | The host whose outage this was folded under. |
| `opened_at` | text NOT NULL | ISO. |
| `resolved_at` | text | ISO; null while open. Set to when it first went missing, once it has been missing long enough. |
| `last_seen_at` | text NOT NULL | ISO. |
| `missing_since` | text | ISO; set while it has been missing from the last look(s), before it is called over. |
| `escalated_step` | integer NOT NULL, default 0 | The highest escalation step already sent for this incident (0 = none); a new incident starts again. |
| `escalated_at` | text | ISO; when that step was sent. |
Resolved rows older than 400 days are deleted, with their notes.
#### `incident_notes`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `incident_id` | integer NOT NULL | → `alert_incidents.id`, deleted with it. |
| `author` | text NOT NULL | The person's name at the time. |
| `body` | text NOT NULL | Up to 4000 characters. |
| `created_at` | text NOT NULL | ISO. |
#### `patch_plans`
Updates on a schedule, one server at a time (services/patchPlans.ts). A plan only says when, to whom and how; each server is updated by an update run.
| Column | Type | Notes |
|---|---|---|
| `id`, `name`, `enabled` | | |
| `days` | text NOT NULL | JSON: weekdays, 0 = Sunday … 6. |
| `start_time`, `timezone` | text NOT NULL | `HH:MM` on the clock of an IANA zone. |
| `tags`, `server_ids` | text NOT NULL | JSON arrays: the servers with any of these tags, and these servers by id. |
| `integration_id`, `project_id`, `template_id`, `template_name` | | The Semaphore playbook (no foreign key, like update runs). |
| `limit_from` | text NOT NULL, default `name` | What ansible's `--limit` is for each server: its name here, or its host name. |
| `stop_on_failure`, `only_with_updates`, `silence_dependents` | bool NOT NULL, default true | Stop at the first failure; leave out a server with nothing waiting; silence what depends on a server while it is updated. |
| `window_minutes` | integer NOT NULL, default 90 | The longest a server is under maintenance. |
| `last_run_date` | text | The local day it last started on, so it starts once a day even across a restart. |
| `created_by`, `created_at` | | |
#### `patch_plan_runs`
One time a plan ran, and how it went for each server.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `plan_id` | integer NOT NULL | → `patch_plans.id`, deleted with it. |
| `plan_name` | text NOT NULL | As it was. |
| `trigger` | text NOT NULL | `schedule` or `manual`. |
| `status` | text NOT NULL | `running`, `done`, `failed` or `cancelled`. |
| `items` | text NOT NULL | JSON: `[{serverId, name, status (pending/running/done/failed/skipped), updateRunId, message, windowIds}]`. |
| `started_by`, `message`, `started_at`, `finished_at` | | |
#### `endpoint_daily`
One row per endpoint check per UTC day: `total` times asked, `ok` of them answered, `ms_sum`/`ms_count` for the average answer time. Kept about two years (`endpoint_results` keeps two weeks); started from the results that existed when it was added. The monthly report's endpoint availability is worked from it. Primary key (`check_id`, `day`); deleted with its check.
#### `endpoint_hourly`
One row per endpoint check per UTC hour (`hour`, ISO): `total`, `ok`, `ms_sum`, `ms_count` and `ms_max` (the slowest good answer). Kept 120 days — between the results (two weeks) and the daily figures (years) — so an answer-time chart can reach back beyond two weeks. Built once from the results already kept when it was added (internal flag `endpointHourlyBackfilled`). Primary key (`check_id`, `hour`); deleted with its check.
#### `api_tokens`
A person's personal read-only API tokens (see [docs/API.md](docs/API.md)): `user_id` (→ `users.id`, **cascade**: they go with the person), `label`, `token_hash` (SHA-256, unique — the secret itself is shown once and not kept), `token_prefix` (its first twelve characters, to tell tokens apart), `created_at`, `last_used_at` (written at most once a minute) and `expires_at` (null = until removed).
#### `renewals`
A certificate, domain registration or secret whose expiry moved at least 20 days later when the app re-read it: `kind` (`certificate`, `domain`, `secret`), `subject` (its name as it was), `at`, `from_date`, `to_date`. Written once per renewal; read by the monthly report.
#### `update_runs`
A playbook run in Semaphore for one server, wrapped in a maintenance window and followed until the server reports again.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL | → `servers.id`, deleted with the server. |
| `integration_id`, `project_id`, `template_id` | integer NOT NULL | Which Semaphore, project and template. `integration_id` is a plain reference, **not a foreign key**, so history stays readable when an integration is removed. |
| `template_name`, `host_limit` | text NOT NULL | The template's name and ansible's `--limit` it was run with (never empty: an update run is for one server). |
| `task_id`, `task_status` | integer, text | Semaphore's run number and its own word for how it is going. |
| `window_id`, `window_created` | integer, bool | The maintenance window put round it, and whether this run made it (a window that was already there is extended and left to run out). |
| `status` | text NOT NULL | `running`, `waiting_for_host`, `done`, `failed` or `cancelled`. |
| `message` | text | What it says now, in words. |
| `started_by` | text | |
| `started_at`, `task_ended_at`, `host_reported_at`, `finished_at` | text | ISO. |
| `updates_before`, `updates_after` | integer | The waiting count before, and from the report that came after. |
| `reboot_required` | bool NOT NULL, default 0 | From that report. |
| `poll_errors` | integer NOT NULL, default 0 | Consecutive times Semaphore didn't answer (ten ends the run). |
#### `runbooks`
Notes about what to do when something is wrong, attached to a server, integration or DNS provider.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `target_type`, `target_id` | text, integer NOT NULL | `server` \| `integration` \| `dns_provider` and its ID. **Not a foreign key**; a note whose target was deleted is simply not shown. Indexed together. |
| `title`, `body` | text NOT NULL | The body is plain text (see README for the little formatting it understands); never rendered as HTML. |
| `category` | text | An alert category (`offline`, `disk`, …) the note is for; null = anything about the target. |
| `updated_by` | text | The person's name at the time. |
| `created_at`, `updated_at` | text NOT NULL | ISO. |
#### `alert_kind_runbooks`
What to do first about a **kind** of alert, whichever server or integration it is about — shown beside every alert of that kind on the Alerts page (*What to do*). The kind is the first part of an alert's key (`disk`, `hetzner-cert`, `sonarr-queue`). One row for each kind; no foreign keys.
| Column | Type | Notes |
|---|---|---|
| `kind` | text PK | |
| `title` | text NOT NULL | |
| `body` | text NOT NULL, default empty | Plain text with the little formatting runbooks use; never rendered as HTML. May be empty when there is a `url`. |
| `url` | text | A page to open (`http` or `https` only); null when there is none. |
| `updated_by` | text | The person's name at the time. |
| `updated_at` | text NOT NULL | ISO. |
#### `assets`
The hardware inventory.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `kind` | text NOT NULL, default `other` | `server`, `storage`, `network`, `power`, `client` or `other`. |
| `manufacturer`, `model`, `serial`, `location`, `rack_unit`, `notes` | text | |
| `purchase_date`, `warranty_until` | text | `YYYY-MM-DD`. |
| `purchase_price` | real | In the currency set under the `inventory` settings key. |
| `end_of_support` | text | `YYYY-MM-DD`: when the maker stops patching it, or you plan to retire it. What the lifecycle report goes by (the warranty's end stands in when this is empty). |
| `replacement_cost` | real | What replacing it is expected to cost, in the same currency. The lifecycle report falls back to `purchase_price`. |
| `power_watts` | integer | Typical draw, for the running cost. |
| `server_id` | integer | The server this is, if it is one. A plain reference, **not a foreign key**: one whose server is gone shows as unlinked. |
| `created_at`, `updated_at` | text NOT NULL | ISO. |
#### `dependencies`
"A needs B" between servers, network devices and integrations: when B is down, A's alert is folded under B's. The "runs on" links of servers are part of the same graph but live on `servers`, and the "connected through" links of network devices on `network_devices`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `from_type`, `from_id` | text, integer NOT NULL | The thing that needs: `server`, `integration` or `device`, and its id. |
| `to_type`, `to_id` | text, integer NOT NULL | The thing it needs. Unique together with the pair above. |
| `created_at` | text NOT NULL | ISO. |
No foreign keys (like `maintenance_windows`): a row whose server or integration is gone is ignored, not an error.
#### `network_devices`
Switches, access points and gateways read from a UniFi controller (see INTEGRATIONS.md), refreshed every five minutes. A device is a node of the dependency map as `device:<id>`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | The controller. Unique together with `external_id`. |
| `external_id` | text NOT NULL | The MAC address, lower case with colons. |
| `site_name`, `name`, `model` | text | |
| `kind` | text NOT NULL | `gateway` \| `switch` \| `access_point` \| `other`. |
| `ip`, `mac` | text | |
| `state` | text NOT NULL | `online` \| `offline` \| `updating` \| `pending` \| `other`. Only `offline` raises an alert. |
| `uptime_seconds` | integer | |
| `firmware` | text | |
| `firmware_updatable` | bool NOT NULL | |
| `uplink_external_id` | text | The MAC of the device this one is connected through; what makes it depend on that device. |
| `offline_since` | text | ISO. When the controller first stopped seeing it online; null while online. The offline alert counts from here. |
| `last_online_at`, `first_seen_at`, `updated_at` | text | ISO. |
A device the controller no longer lists is deleted on the next read. Dependencies written by hand that mention a removed device are ignored.
#### `network_server_links`
Which server is plugged into which network device, worked out on every UniFi read: a client the controller lists whose IP address is exactly one server's own. Replaced as a whole on a read that lists any clients; kept as it was when it lists none.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | Unique together with `server_id` and `client_mac`. |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `device_external_id` | text NOT NULL | The MAC of the switch or access point (`network_devices.external_id`). |
| `client_mac` | text NOT NULL | The server's own MAC as the controller sees it. |
| `port` | integer | The switch port, where the controller says. |
| `wired` | bool NOT NULL | False for a client on Wi-Fi. |
| `updated_at` | text NOT NULL | ISO. |
#### `network_segments`
The networks (VLANs) and Wi-Fi names of a UniFi controller, replaced as a whole on every read. Passphrases are never stored.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | Unique together with `kind` and `external_id`. |
| `kind` | text NOT NULL | `network` \| `ssid`. |
| `external_id`, `site_name`, `name` | text | |
| `enabled` | bool NOT NULL | |
| `vlan_id` | integer | |
| `subnet`, `purpose` | text | A network's address range and what it is for. |
| `security`, `network_name` | text | A Wi-Fi name's security, and the network its clients land on. |
| `updated_at` | text NOT NULL | ISO. |
#### `notes`
A free-text note about a server or a network device.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `target_type`, `target_id` | text, integer NOT NULL | `server` or `device`, and its id. Unique together: one note each. Not a foreign key (a removed thing's note is ignored). |
| `body` | text NOT NULL | The text, with the small formatting runbooks use. Saving an empty one deletes the row. |
| `updated_by` | text | Who last saved it, as a name. |
| `updated_at` | text NOT NULL | ISO. |
#### `note_photos`
A photo on the note of a server or a network device — up to 12 each. The picture itself is in the row, so a database backup has it. Exactly one of `server_id` and `device_id` is set; both are foreign keys with **cascade**, so removing the server or the device removes its photos; each is indexed.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id`, `device_id` | integer | The server or the device it is on. |
| `content_type` | text NOT NULL | `image/jpeg`, `image/png`, `image/gif` or `image/webp` — told from the bytes when it was added, never from what the upload said. |
| `data` | blob NOT NULL | The picture, up to 4 MB (the browser makes it far smaller first). |
| `size` | integer NOT NULL | Bytes. |
| `caption` | text | Up to 120 characters. |
| `created_by` | text | As a name. |
| `created_at` | text NOT NULL | ISO. |
#### `todos`
The small jobs of **Operations → To do**.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `title` | text NOT NULL | |
| `detail` | text | |
| `due_date` | text | `YYYY-MM-DD`. A job with a day, while open, is on the Coming up calendar. |
| `assignee_user_id` | integer → `users.id`, **set null** | Who it is handed to. |
| `assignee_name` | text | Their name when it was handed over, so it still reads if they are removed. |
| `target_type`, `target_id` | text, integer | `server` or `device`, and its id, when the job is about one. Not a foreign key. |
| `created_by`, `created_at` | text | |
| `done_at`, `done_by` | text | ISO and a name; null while open. |
#### `ha_watched`
The Home Assistant entities somebody chose to watch (see INTEGRATIONS.md).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | The Home Assistant. Unique together with `entity_id`. |
| `entity_id` | text NOT NULL | `sensor.ups_battery`. |
| `name` | text | What to call it here; the entity's own friendly name when null. |
| `above`, `below` | real | Limits for a numeric value: an alert when it is over `above` or under `below`. |
| `created_at` | text NOT NULL | ISO. |
#### `ha_entities`
What the last read said about each watched entity. Primary key (`integration_id`, `entity_id`); `integration_id` is a foreign key with **cascade**. Rows of an entity no longer watched are removed on the next read.
| Column | Type | Notes |
|---|---|---|
| `friendly_name`, `unit`, `device_class` | text | |
| `state` | text NOT NULL | As Home Assistant says it; `missing` when it is no longer in Home Assistant at all. |
| `value` | real | The state as a number, when it is one. |
| `last_changed` | text | ISO, from Home Assistant. |
| `unavailable_since` | text | ISO. When it was first seen `unavailable`, `unknown` or missing; kept until it speaks again. The alert counts from here. |
| `updated_at` | text NOT NULL | ISO. |
#### `ha_readings`
A numeric value of a watched entity at a moment, for the chart: one at most every two minutes, deleted after 35 days. `integration_id` is a foreign key with **cascade**; (`integration_id`, `entity_id`, `at`) is indexed.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `entity_id` | text NOT NULL | |
| `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 | |
#### `nextcloud_state`
How a Nextcloud (an integration of type `nextcloud`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `maintenance`, `needs_upgrade` | bool NOT NULL, default 0 | From status.php. |
| `detail` | bool NOT NULL, default 0 | Whether the monitoring app answered (an administrator's app password is needed). |
| `free_bytes`, `users`, `files`, `active_24h`, `app_updates` | integer | Null when the monitoring app was not asked or did not say. |
| `core_update` | text | The version Nextcloud says is available (`newer` when it says only that there is one); null when none is, or not asked. |
| `cron_state`, `cron_text` | text | Nextcloud's own *Cron last run* check: `success`, `info`, `warning` or `error`, and what it said. **Null when it could not be asked** (no login, or before Nextcloud 28) — not the same as fine. |
| `setup_issues` | text | JSON: name, severity (`error` or `warning`), text — its other setup checks that report a problem, at most 40. Null when the checks could not be asked. |
| `updated_at` | text NOT NULL | ISO. |
#### `dockhand_vulnerabilities`
What Dockhand's own stored vulnerability scans add up to for each of its Docker hosts (its *environments*), as last read — one row for each Dockhand integration and environment, replaced at every read (every fifteen minutes; a host Dockhand no longer lists is dropped). `integration_id` is a foreign key with **cascade**; the primary key is (`integration_id`, `environment_id`). Nothing is scanned by this app — it reads only what Dockhand kept.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `environment_id` | integer PK | Dockhand's own id for the Docker host. |
| `environment_name` | text NOT NULL | |
| `critical`, `high`, `medium`, `low` | integer | The counts across the host's scanned images. **Null when the count could not be read** (an older Dockhand, a host it cannot reach) — which is not the same as 0. |
| `images_scanned`, `total_images` | integer | How many of the host's images have a scan; the rest are not known to be clean. |
| `findings` | text NOT NULL, default `[]` | JSON: the critical findings (CVE, package, installed and fixed version, image, the containers that use it), at most 100. |
| `images`, `images_at` | text | JSON: the images this host's running containers use, each with when it was built (`image`, `created`, `containers`), and when that was read (migration `0076`). Null: never read, or could not be. |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:dockerVulnSync`.
#### `netbox_state`
How a NetBox (an integration of type `netbox`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `workers_running` | integer | How many RQ workers; **null** when /status/ did not say (which is not the same as 0). |
| `devices`, `virtual_machines`, `prefixes`, `ip_addresses` | integer | Counts; null when not read. |
| `ips` | text | JSON array of the addresses NetBox holds, without the prefix length, at most 5000; null when they could not be listed. |
| `updated_at` | text NOT NULL | ISO. |
#### `speedtest_results`
The speed tests a Speedtest Tracker (an integration of type `speedtest`) has made, one row each, kept for 90 days. The primary key is (`integration_id`, `result_id`) and `integration_id` is a foreign key with **cascade**; an index on (`integration_id`, `at`). A result is stored once under Speedtest Tracker's own id and never changed afterwards. How the last read went is kept in `settings`, key `_internal:speedtestSync`.
| Column | Type | Notes |
|---|---|---|
| `integration_id`, `result_id` | integer PK | `result_id` is Speedtest Tracker's own id for the result. |
| `at` | text NOT NULL | ISO: when the test was made (the time Ookla gives, else `created_at` taken as UTC). |
| `status` | text NOT NULL | `completed`, `failed`, `skipped` … |
| `download_bps`, `upload_bps` | real | Bits per second; null for a test that has none (failed, skipped). |
| `ping_ms` | real | Milliseconds. |
| `healthy` | bool | Speedtest Tracker's own judgement by its thresholds; null when it did not say. |
#### `cost_items`
Things paid for by hand (a domain, a VPN, a licence, a subscription), one row each — the Costs page. What can be read (a Hetzner project's estimate) is not here. No foreign keys.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `amount` | real NOT NULL | What is paid each time, with VAT. |
| `currency` | text NOT NULL | Three capital letters. Totals are per currency; none is converted. |
| `period` | text NOT NULL | `month` or `year`. |
| `category` | text NOT NULL, default `Other` | Free text (Hosting, Domains, Subscriptions …). |
| `renews_on` | text | YYYY-MM-DD: a day it is (or will first be) billed. An anchor: the next time it falls is worked out from it and shown in Coming up. |
| `note` | text | |
| `created_at`, `updated_at` | text NOT NULL | ISO. |
#### `hetzner_state`
How a Hetzner Cloud project (an integration of type `hetzner`; a token belongs to one project) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `servers` | text NOT NULL, default `[]` | JSON: each server as read (status, type, location, addresses, traffic this month and included, rescue mode, backup window, monthly price) plus what the app has seen of it between reads: `lastRunningAt`, `statusSince`, `rescueSince`. Hetzner does not say when a server went off; these are the times of the reads that showed it. |
| `volumes`, `images` | text | JSON; the volumes, and the snapshots and backups. **Null when they could not be asked** — which is not the same as none. |
| `cost` | text | JSON: the monthly estimate at list prices including VAT (currency, servers, backups, volumes, snapshots, IPs, load balancers, floating IPs, total). Null when the price list could not be read. |
| `load_balancers`, `floating_ips`, `certificates` | text | JSON: each load balancer with the health of its targets, each floating IP and what it points at, each certificate with when it ends. **Null when they could not be asked.** (Migration `0072`.) |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:hetznerSync`.
#### `fragnet_state`
How a Fragnet game panel account (an integration of type `fragnet`; an API key belongs to one account) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history: what is stored is the last good read.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `servers` | text NOT NULL, default `[]` | JSON: each game server as read (the panel's short id, name, game, addresses, SFTP, limits, running state, what it uses, backups, schedules, database count) plus what the app has seen of it between reads: `stateSince` and `firstSeenAt`. A part that could not be read (backups, schedules, databases, usage) is **null** — which is not the same as none. |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:fragnetSync`.
#### `arr_state`
How a Sonarr, Radarr or Prowlarr (an integration of type `sonarr`, `radarr` or `prowlarr`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history: what is stored is the last good read.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `health` | text NOT NULL, default `[]` | JSON: what its own checks found (source, type, message). |
| `queue` | text | JSON `{ total, items }`: how many downloads there are and the first hundred (title, status, how it is judged, what it says is wrong, size, when it was added, client, indexer). **Null when it could not be read** — and always for Prowlarr, which has none. |
| `disks` | text | JSON: path, free and total bytes; null when it could not be read. |
| `missing` | integer | Wanted items with no file (Sonarr, Radarr); null when not read. |
| `indexers` | text | JSON, Prowlarr only: each indexer and, if Prowlarr has switched it off after failures, until when. |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:arrSync`.
#### `adguard_state`
How an AdGuard Home (an integration of type `adguard`) is right now, one row each, replaced at every read (every two minutes). `integration_id` is the primary key and a foreign key with **cascade**. No history: what is stored is the last good read, plus two clocks only this app can keep.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `running`, `protection_enabled` | integer NOT NULL, default 1 | Whether its DNS server runs; whether protection is on. |
| `protection_off_since` | text | ISO: the first read that showed protection off; null while it is on. |
| `dns_port` | integer NOT NULL, default 53 | |
| `stats`, `filters` | text | JSON: the statistics (queries, blocked, average time, top names and clients) and the filter lists (name, on or off, rules, when updated). **Null when they could not be read.** |
| `probe` | text | JSON: the real DNS question — `{ ok, ms, error, name, host }`. |
| `probe_fail_since` | text | ISO: the first read in which the question went unanswered; null while it is answered. |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:adguardSync`.
#### `grafana_state`
How a Grafana (an integration of type `grafana`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. No history.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `rules` | text | JSON `{ total, items }`: how many alert rules there are, and those firing, pending or in error (name, folder, group, state, health, error, severity, summary, since when). **Null when they could not be read.** |
| `datasources` | text | JSON: each data source with Grafana's health check of it (`ok` is true, false, or null when its type has none). Null when they could not be listed. |
| `updated_at` | text NOT NULL | ISO. |
How the last read went is kept in `settings`, key `_internal:grafanaSync`.
#### `n8n_state`
How an n8n (an integration of type `n8n`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `workflows` | text NOT NULL, default `[]` | JSON: id, name, active, lastStatus, lastAt, failed24h — the last outcome and the failures of the last day are worked out from the newest 250 runs. |
| `executions_known` | bool NOT NULL, default 0 | False when the runs could not be asked, so no last outcome is known. |
| `updated_at` | text NOT NULL | ISO. |
#### `immich_state`
How an Immich (an integration of type `immich`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version`, `latest_version` | text | |
| `update_available` | bool NOT NULL, default 0 | |
| `disk_size`, `disk_used` | integer | Bytes, of the disk under the library. |
| `disk_percent` | real | |
| `photos`, `videos`, `usage_bytes` | integer | Null when the statistics could not be asked (they need an administrator's key). |
| `queues` | text | JSON: name, active, waiting, failed, paused. **Null** when the queues could not be asked (not the same as `[]`). |
| `updated_at` | text NOT NULL | ISO. |
#### `paperless_state`
How a Paperless-ngx (an integration of type `paperless`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version`, `latest_version` | text | |
| `update_available` | bool NOT NULL, default 0 | |
| `storage_total`, `storage_available` | integer | Bytes, of the disk the documents are on. |
| `components` | text | JSON: name, status (`OK`, `WARNING`, `ERROR`), error — database, redis, celery, index, classifier, sanity_check. **Null** when the status could not be asked (it needs a superuser). |
| `documents`, `inbox` | integer | |
| `failed` | text | JSON: file, error, at — imports that failed in the last week and were not dismissed. Null when the tasks could not be asked. |
| `updated_at` | text NOT NULL | ISO. |
#### `prometheus_state`
How a Prometheus (an integration of type `prometheus`) is right now, one row each, replaced at every read (every two minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version` | text | |
| `jobs` | text | JSON: job, up, down. **Null** when the targets could not be asked (not the same as `[]`). |
| `down` | text | JSON: job, instance, error, since — `since` is when it was first seen down, carried over from read to read. Null with `jobs`. |
| `alerts` | text | JSON: name, severity, state, summary, instance, activeAt. Null when they could not be asked. |
| `updated_at` | text NOT NULL | ISO. |
#### `authentik_state`
How an Authentik (an integration of type `authentik`) is right now, one row each, replaced at every read (every five minutes). `integration_id` is the primary key and a foreign key with **cascade**. There is no history table.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `version`, `latest_version` | text | As Authentik says. |
| `outdated` | bool NOT NULL, default 0 | A newer version is out. |
| `workers` | integer | How many are connected; null when they could not be asked (which is not the same as none). |
| `outposts` | text NOT NULL, default `[]` | JSON: name, type, providers, healthy, instances, outdated, lastSeen. |
| `certificates` | text NOT NULL, default `[]` | JSON: name, expires (those Authentik does not renew itself). |
| `tokens` | text NOT NULL, default `[]` | JSON: identifier, intent, user, expires (API tokens and app passwords that expire). |
| `failed_logins_24h`, `config_errors_24h` | integer | In the last day (a page of 100 means "at least"); null when the events could not be read. |
| `last_config_error` | text | The newest configuration error's message. |
| `updated_at` | text NOT NULL | ISO. |
#### `jellyfin_state`
How a Jellyfin (an integration of type `jellyfin`) is right now, one row each, replaced at every read (every two minutes). `integration_id` is the primary key and a foreign key with **cascade**.
| Column | Type | Notes |
|---|---|---|
| `integration_id` | integer PK | |
| `server_name`, `version`, `os` | text | As Jellyfin says. |
| `pending_restart`, `update_available` | bool NOT NULL, default 0 | |
| `streams` | text NOT NULL, default `[]` | JSON: who is streaming what (user, client, device, title, transcoding, paused). |
| `tasks` | text NOT NULL, default `[]` | JSON: the scheduled tasks and how each last ended. |
| `movies`, `series`, `episodes`, `songs` | integer | Item counts; null when not said. |
| `failed_logins_24h` | integer | Null when the activity log could not be read. |
| `updated_at` | text NOT NULL | ISO. |
#### `jellyfin_readings`
How many were streaming, and how many of those were transcoded, at a moment: one every five minutes and at once when either number 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. |
| `streams`, `transcodes` | integer NOT NULL | |
#### `service_levels`
A service-level target (Monitoring → Service levels): what a thing is held to, measured over calendar months. No foreign keys: the thing measured is a plain reference, and a target whose subject is removed is shown as having nothing to measure.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `subject_type` | text NOT NULL | `endpoint` (an endpoint check), `server` or `integration`. |
| `subject_id` | integer NOT NULL | The id of that thing. |
| `target` | real NOT NULL | Percent, 90 to 99.999. |
| `alert` | bool NOT NULL, default 1 | Warn at 80 % of the month's error budget, and when it is overspent. |
| `created_by` | text | |
| `created_at` | text NOT NULL | |
Nothing about how a target is doing is stored: it is worked out when asked, from `endpoint_daily` and the audit log.
#### `duplicati_sources`
A machine running Duplicati that reports to this app. `token_hash` is the SHA-256 of the secret in its address (shown once, never stored); `server_id` is a plain reference to the server it runs on (maintenance on it silences the alerts).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `token_hash` | text NOT NULL, unique | |
| `token_prefix` | text NOT NULL | The first characters, to tell addresses apart. |
| `server_id` | integer | |
| `created_by`, `created_at` | text | |
| `last_report_at` | text | ISO; the last time anything arrived. |
#### `duplicati_backups`
One backup job of one source, as its last report left it; learned from a first report, by name (unique with `source_id`). `source_id` is a foreign key with **cascade**.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `source_id`, `name` | integer, text | |
| `last_report_at`, `last_begin`, `last_end` | text | ISO. |
| `last_result` | text | `Success`, `Warning`, `Error` or `Fatal`. |
| `duration_seconds`, `examined_files`, `size_bytes`, `added_files`, `modified_files`, `deleted_files` | integer | As the last report said; null when it did not. |
| `warnings`, `errors` | integer NOT NULL, default 0 | |
| `message` | text | The first error, or warning. |
| `last_success_at` | text | ISO; a run with warnings counts. |
| `consecutive_failures` | integer NOT NULL, default 0 | Critical from 2. |
| `expected_hours` | integer NOT NULL, default 48 | How long it may go without succeeding. |
| `alert` | bool NOT NULL, default 1 | |
#### `duplicati_runs`
Each report of a backup, for its history: 400 days and at most 400 per job. `backup_id` is a foreign key with **cascade**; (`backup_id`, `at`) is indexed.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `at` | text NOT NULL | ISO; when the backup finished. |
| `result` | text NOT NULL | |
| `duration_seconds`, `size_bytes`, `files_changed` | integer | |
| `warnings`, `errors` | integer 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>]`.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | Shown in the alert's message, in square brackets. |
| `enabled` | bool NOT NULL, default 1 | |
| `metric` | text NOT NULL | `cpu`, `mem`, `disk` (use, percent) or `disk_temp` (°C, from the SMART report). |
| `mount` | text | For `disk`: one mount point or drive; null = every disk. |
| `operator` | text NOT NULL, default `above` | `above` or `below`. |
| `threshold` | real NOT NULL | Percent (0–100), or °C (0–150). |
| `for_minutes` | integer NOT NULL, default 0 | How long every sample must have been past the limit (0–1440); always 0 for `disk_temp`. |
| `severity` | text NOT NULL, default `warning` | `warning` or `critical`. |
| `server_id` | integer | One server. A plain reference, **not a foreign key**: a rule for a server that is gone judges nothing. Not together with `tag`. |
| `tag` | text | Servers with this tag; with a null `server_id` too, every server. |
| `created_by`, `created_at` | text | |
#### `storage_series`
A pool an integration reports — a Proxmox storage or root filesystem, a Synology volume — so that it can be forecast (see README, *Forecasts for Proxmox storage and Synology volumes*).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `integration_id` | integer NOT NULL → `integrations.id`, **cascade** | Unique together with `key`. |
| `key` | text NOT NULL | `<node>:storage:<id>`, `shared:<id>`, `<node>:rootfs` (Proxmox) or `volume:<id>` (Synology). |
| `label` | text NOT NULL | What to call it in a message. |
| `latest_percent` | real NOT NULL | The newest reading. |
| `used_bytes`, `total_bytes` | integer | |
| `updated_at` | text NOT NULL | ISO; a pool not reported for 30 days is deleted. |
#### `storage_samples`
One reading of a pool an hour at most, kept 400 days. `series_id` is a foreign key with **cascade**; (`series_id`, `at`) is indexed.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `at` | text NOT NULL | ISO. |
| `value` | real NOT NULL | Percent used. |
#### `alert_snoozes`
An alert hidden until a time (see README, *Snooze*). Keyed like `alert_acks`, by the alert's id on the Alerts page; no foreign keys.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `alert_id` | text NOT NULL, unique | |
| `condition_key` | text NOT NULL | The key behind it, which the notifications carry (so they can be held). |
| `message` | text NOT NULL | What it said when it was snoozed. |
| `until` | text NOT NULL | ISO. When it has passed, an alert that is still there is announced again and the row is deleted. A **closed** alert has `9999-12-31T00:00:00.000Z`, which never comes. |
| `kind` | text NOT NULL, default `snooze` | `snooze`, or `closed` ("dealt with or accepted": hidden with no end, until it gets more serious than `severity` or has been gone for 30 minutes). |
| `severity` | text | For a closed alert: `critical`, `warning` or `info` as it was when it was closed. |
| `note` | text | For a closed alert: why. (It is also written on the incident.) |
| `snoozed_by`, `snoozed_at` | text NOT NULL | |
| `last_seen_at` | text NOT NULL | ISO; the last time the alert was there. A row whose alert has been gone for 30 minutes is deleted. |
#### `push_subscriptions`
A browser or phone that asked for push notifications, one row per device.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `user_id` | integer NOT NULL | → `users.id`, deleted with the user. |
| `endpoint` | text NOT NULL, unique | The address of the browser's push service. It is a secret: with the keys below it can write to that device. |
| `p256dh`, `auth` | text NOT NULL | The browser's public key and authentication secret, which every message is encrypted with. |
| `label` | text | What the person calls it, or the browser it is. |
| `created_at` | text NOT NULL | ISO. |
| `last_success_at` | text | When the push service last accepted a message for it. |
| `min_severity` | text | `warning` or `critical`: this browser only wants alerts at least that bad. Null = every severity. |
| `categories` | text | JSON array of the kinds of alert it wants (`offline`, `disk`, …). Null = every kind. |
A subscription is removed when the push service says it is gone (HTTP 404 or 410), when its owner or an administrator removes it, and all of them are removed if the server's own key pair has to be made again.
#### `endpoint_checks`
A web address, TCP port or TLS certificate the app asks about every few minutes (see the README). The last answer is kept on the row.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `kind` | text NOT NULL | `http`, `tcp` or `tls`. |
| `target`, `port` | text NOT NULL, integer | http: the address. tcp and tls: the host, and the port. |
| `expect_status`, `keyword` | text | http only: the good status codes (`200-204, 401`; null = 200–399) and a word the page must contain. |
| `value_path`, `value_op`, `value_expected`, `value_unit` | text | http only: judge a value in a JSON answer — where it is (`data.result[0].value[1]`), how it must compare (`<` `<=` `>` `>=` `=` `!=` `contains` `exists`), what to, and a unit to show. All null for a check that judges no value. |
| `header_name`, `header_value` | text | http only: a header sent with the request. The value is stored encrypted (`enc:v1:`) when an encryption key is set, and is never returned by the API. |
| `last_value` | text | What a value check read the last time. |
| `insecure` | bool NOT NULL, default 0 | Accept a certificate that isn't trusted (its expiry is still watched). |
| `interval_minutes`, `timeout_seconds`, `failures_before_alert`, `warn_days` | integer NOT NULL | Defaults 5, 10, 2 and 14. |
| `server_id` | integer | The server it is about. A plain reference, **not a foreign key**: maintenance on that server silences the check's alerts; one whose server is gone is just unlinked. |
| `enabled` | bool NOT NULL, default 1 | |
| `last_checked_at`, `last_ok`, `last_message`, `last_response_ms` | text, bool, text, integer | How the latest ask went. |
| `cert_expires_at` | text | ISO; when the certificate it showed runs out. |
| `consecutive_failures` | integer NOT NULL, default 0 | A problem once this reaches `failures_before_alert`. |
| `last_change_at` | text | When it last went from working to failing or back. |
| `created_at` | text NOT NULL | |
#### `endpoint_results`
One row per answer, kept for two weeks: uptime, average answer time and the run of recent results come from these.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `check_id` | integer NOT NULL | → `endpoint_checks.id`, deleted with it (indexed with `at`). |
| `at` | text NOT NULL | ISO. |
| `ok` | bool NOT NULL | |
| `ms`, `message` | integer, text | |
| `value` | real | The number a value check read, when it is one; what the value chart is drawn from. |
#### `heartbeats`
A job that reports in: it calls `/api/heartbeat/<token>` when it finishes, and the app speaks up when the call doesn't come in time (services/heartbeats.ts).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `token` | text NOT NULL, unique | The secret part of the address (`hb_…`). Kept as it is, not hashed, because the address has to be shown again; all it allows is "I'm alive". |
| `period_minutes`, `grace_minutes` | integer NOT NULL | How often it should report, and how much later is still fine (default 10). |
| `server_id` | integer | Soft reference to the server it runs on, so its maintenance silences the alerts. |
| `enabled` | bool NOT NULL, default true | A switched-off heartbeat still takes calls. |
| `notes` | text | |
| `last_ping_at`, `last_status` | text | When the last call that ended a run came in, and `ok` or `fail`. |
| `last_message`, `last_duration_ms` | text, integer | The note sent with it, and how long the run took when it said it had started. |
| `last_start_at` | text | ISO; the last `/start` call. |
| `ping_count`, `created_at` | integer, text | |
#### `heartbeat_pings`
The recent calls to each heartbeat, for its history; kept two weeks.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `heartbeat_id` | integer NOT NULL | → `heartbeats.id`, deleted with it (indexed with `at`). |
| `at` | text NOT NULL | ISO. |
| `kind` | text NOT NULL | `ok`, `fail` or `start`. |
| `duration_ms`, `message` | integer, text | |
#### `restore_tests`
Each time somebody tried to restore a backup, and how it went. History is kept; the newest per subject is what counts.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `subject_key` | text NOT NULL | `guest:<integration id>:<vmid>` for a Proxmox guest, `custom:<name>` for anything else. Not a foreign key (indexed with `tested_at`). |
| `label` | text NOT NULL | What to call it. |
| `tested_at` | text NOT NULL | `YYYY-MM-DD`. |
| `result` | text NOT NULL | `ok`, `partial`, `failed` or `not_needed`. |
| `note`, `tested_by` | text | |
| `created_at` | text NOT NULL | |
#### `metrics_tokens`
Read-only access to `/metrics` for Prometheus. Only a hash of each secret is stored.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `label` | text NOT NULL | |
| `token_hash` | text NOT NULL, unique | SHA-256 of the secret, which is shown once and never stored. |
| `token_prefix` | text NOT NULL | The first characters, to tell tokens apart in the list. |
| `created_by` | text | |
| `created_at` | text NOT NULL | |
| `last_used_at` | text | ISO; updated at most once a minute. |
#### `event_webhooks`
URLs sent a signed JSON message when an alert begins or ends or maintenance starts or finishes.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `label` | text NOT NULL | |
| `url` | text NOT NULL | http or https, with no user name or password in it. |
| `secret` | text | Signs each message (HMAC-SHA256). Stored encrypted (`enc:v1:`) when an encryption key is set; never returned by the API. |
| `events` | text NOT NULL | JSON array of `alert.opened`, `alert.resolved`, `maintenance.started`, `maintenance.ended`. |
| `enabled` | bool NOT NULL, default 1 | |
| `created_by` | text | |
| `created_at` | text NOT NULL | |
| `last_attempt_at`, `last_result` | text | When it was last sent to and what came back (`200`, or what went wrong). |
#### `webhook_deliveries`
The log of what was sent to each event webhook (Settings → API and webhooks → Sent): one row per message, with its second try counted in. Trimmed to the newest 100 per webhook and 14 days each time one is added.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `webhook_id` | integer NOT NULL | FK → `event_webhooks.id`, cascade. Indexed with `created_at`. |
| `event` | text NOT NULL | `alert.opened` … |
| `delivery_id` | text NOT NULL | The message's `id` and `X-HLM-Delivery`; a resend keeps it. |
| `attempts` | integer NOT NULL, default 1 | 2 when the first try failed. |
| `ok` | bool NOT NULL | Whether a `2xx` came back. |
| `result` | text NOT NULL | `200`, or what went wrong. |
| `body` | text NOT NULL | The JSON that was sent, cut at 16 001 characters (longer than 16 000 means it cannot be sent again). |
| `retry_of` | integer | The `id` of the delivery this one sent again by hand. |
| `created_at` | text NOT NULL | ISO. |
#### `share_links`
Addresses that open a read-only page without signing in (Settings → Share
links): the wall display, or a status page. Only a hash of the secret is stored.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `label` | text NOT NULL | What it is for, e.g. "Hall TV". |
| `token_hash` | text NOT NULL, unique | SHA-256 of the secret in the address; the secret itself is shown once and never stored. |
| `token_prefix` | text NOT NULL | The first characters of the secret, to tell links apart in the list. |
| `detail` | text NOT NULL, default `summary` | For a wall: `summary` (numbers only) or `names` (also the names of what is wrong, in maintenance, and the integrations). Not used by a status page. |
| `kind` | text NOT NULL, default `wall` | `wall`, `status` or `calendar` (an iCalendar feed of what is coming up; `detail` says whether it carries names). Each kind's address opens only that kind. |
| `title`, `message` | text | A status page's heading and its optional message; null for a wall. |
| `created_by` | text | The administrator's name at the time. |
| `created_at` | text NOT NULL | |
| `expires_at` | text | ISO; null = until removed. |
| `last_used_at` | text | ISO; updated at most once a minute. |
#### `status_items`
What a status page shows, in order.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `link_id` | integer NOT NULL | → `share_links.id`, deleted with the link. |
| `position` | integer NOT NULL | Order on the page (indexed with `link_id`). |
| `label` | text NOT NULL | The name people will recognise — the only thing about it the public sees. |
| `kind` | text NOT NULL | `server`, `integration` or `monitor`. |
| `target_id` | integer NOT NULL | The server, the integration, or the Uptime Kuma a monitor belongs to. A plain reference, **not a foreign key**: if it is removed the item reads "can't tell". |
| `monitor_id` | text | Uptime Kuma's own id for the monitor (`kind` = `monitor`). |
## What's stored inside the JSON columns
| Column | Shape |
|---|---|
| `servers.ip_addresses` | `["10.0.0.5", "fd00::5"]` |
| `servers.disks` | `[{ "mount": "/", "sizeBytes": 32000000000, "usedBytes": 9000000000 }]` |
| `servers.listening_ports` | `[{ "protocol": "tcp", "port": 22, "address": "0.0.0.0", "process": "sshd" }]` |
| `servers.last_port_scan` | `{ "at": "<ISO>", "address": "10.0.0.5", "from": 1, "to": 1024, "open": 3, "refused": 1010, "filtered": 11, "responded": true }` |
| `servers.tags` | `["prod", "media"]` |
| `audit_log.detail` | Free-form per action — e.g. `{ "name": "pve1" }`, or for settings `{ "sections": [...], "changes": { "<section>": { "<field>": { "from": …, "to": … } } } }`. For the notification channels (Gotify, ntfy, SMTP, webhook) only the field *names* that changed are recorded, never values. |
| `integrations.config` | The non-secret fields for that integration type (table below). |
| `dns_providers.config` | Non-secret provider settings (base URL, zone list, …). |
**`integrations.config` by type** (the secret fields go to `integration_credentials` instead):
| Type | In `config` | Encrypted separately |
|---|---|---|
| `proxmox` | `url`, `tokenId`, `insecure` | `tokenSecret` |
| `pbs` | `url`, `tokenId`, `insecure` | `tokenSecret` |
| `synology` | `url`, `username`, `insecure` | `password` |
| `semaphore`, `gitea`, `dockhand` | `url` | `token` |
| `tailscale` | `tailnet` | `apiKey` |
| `uptimekuma` | `url`, `username`, `loginUsername`, `syncMaintenance` | `password` (an API key, or the password on old installs), `loginPassword` |
| `phpipam` | `url`, `appId`, `insecure` | `token` |
| `osticket` | `host`, `port`, `database`, `username`, `tablePrefix`, `apiUrl`, `apiInsecure` | `password`, `apiKey` |
| `unifi` | `url`, `username`, `site`, `selfHosted`, `insecure` | `apiKey` (or `password`, with `username`) |
| `npm` (Nginx Proxy Manager) | `url`, `email`, `insecure` | `password` |
| `homeassistant` | `url`, `insecure` | `token` |
## Settings keys
Each section is one row in `settings`, with a JSON object as its value. Fields
that were never changed aren't stored; the app fills in defaults when reading.
| Key | Holds |
|---|---|
| `gotify`, `ntfy`, `smtp`, `webhook` | The four notification channels: enabled, address, and credentials (token / password / secret). The credential fields are stored encrypted (prefix `enc:v1:`) — see [Retention and backups](#retention-and-backups). |
| `routing` | Routing rules: `rules`, an ordered array of `{id, name, enabled, categories, minSeverity, tags, channels}` — the first enabled rule a notification matches decides which channels get it (empty `channels` = nobody). |
| `escalation` | `enabled` (false) and up to three `steps` of `{afterMinutes, minSeverity, channels, extraEmail, evenInQuietHours}`, in time order. |
| `webPush` | Push to phones and browsers: `enabled` (false) and `contact` (an email or https address the push services may reach whoever runs this on; blank is fine). Who is subscribed is in `push_subscriptions`; the server's key pair is below. |
| `notifications` | Which events notify (`dnsAdd`, `healthAlerts`, …), the daily-reminder time (`secretCheckTime`, default `08:00`) and `timezone` (default `UTC`), and the integration-failure threshold (default 3). |
| `quietHours` | `enabled`, `start`, `end`, `criticalThrough` (false — a critical alert is sent at once even inside the window). |
| `away` | Away mode: `until` (ISO, null when nobody is away), `from` (ISO, null when it began when it was set, or a later moment for one planned ahead), `criticalThrough` (true — critical alerts are still sent), `note`. An away stretch whose `until` has passed is cleared by a check every minute, which also sends what was held. |
| `signIn` | Roles from groups: `roleFromGroups` (false), `groupsClaim` (`groups`), `adminGroups`, `operatorGroups`, `otherwise` (`viewer` or `keep`). |
| `profilePictures` | Where pictures of people come from: `identityProvider` (false) and `gravatar` (false). Either one means the server fetches pictures from an outside address; they are checked, kept for a day and served from this app. |
| `alertActions` | `enabled` (false): whether notifications carry buttons and links to acknowledge, silence and snooze (see NOTIFICATIONS.md). The links are signed tokens, so nothing about them is stored. |
| `selfBackup` | The daily backup of this database: `enabled` (true), `time` (`HH:MM`, default `03:30`, in the notification time zone) and `keep` (14 — how many daily ones are kept). |
| `agents` | `autoUpdate` (false): whether agents that are behind replace themselves. |
| `inventory` | `currency` (a short name, may be blank) and `pricePerKwh` (null) — what the inventory's running cost is worked out with. |
| `monthlyReport` | The monthly report: `enabled` (false), `day` (1–28, default 1) and `time` (`HH:MM`, default `08:00`), in the notification time zone; `quarterly` and `annual` (both false) add the quarter's report after March, June, September and December, and the year's after December. |
| `digest` | The weekly digest: `enabled` (false), `day` (0 = Sunday … 6; default 1, Monday) and `time` (`HH:MM`, default `08:00`), in the notification time zone. |
| `healthChecks` | `restoreTestDays` (0 = off — how long a guest's last passing restore test counts; a failed one is always raised), `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30), `diskForecastDays` (14; 0 = off — how far ahead a filling disk is flagged on the Alerts page), `backupStaleHours` (48; 0 = off — how old a Proxmox guest's newest backup may be), `newPortAlerts` (true — warn when a server starts listening on a TCP port that is not in its baseline and not noted), `flapRaises` (3; 0 = off — raises of one alert within an hour that make it "flapping" so its messages are held; see NOTIFICATIONS.md), `deviceOfflineMinutes` (10 — how long a UniFi device may be offline before it is raised), `osSupportWarnDays` (90; 0 = off), `baselineAlerts` (true — warn when CPU or memory over the last hour is far above what the server's own history says is normal for this hour of the week; see docs/MONITORING.md), `containerAlerts` (true — warn when a Docker container is broken), `vulnerabilityAlerts` (true — warn when Dockhand's scans found critical vulnerabilities; an older stored setting without it counts as on) and `containerIgnore` (a list of container names or `host/name`, `*` allowed, to leave alone). The baselines themselves are not stored: they are worked out from `server_metrics_rollup` (hourly rows, `grain = 'h'`) when needed. A server can override each of these (see `servers.thresholds`). |
| `logRetention` | `enabled`, `retentionDays` (90), `intervalHours` (24). |
| `display` | `dateFormat`, `timeFormat`, `pageSize`. |
| `providerColors`, `integrationColors` | Badge colours, by provider / integration type. |
| `consistency` | `excludedRanges` — addresses the Consistency and IP Addresses pages ignore. Default `["172.16.0.0/12"]` (Docker's networks). |
| `alertTickets` | Opening osTicket tickets for alerts: `enabled`, `integrationId`, `severities`, `categories`, `requesterName`/`requesterEmail`, `topicId`, `priorityId`, `notifyStaff`, `existingProblems`, `confirmChecks`, `summaryAbove`, `reopenAfterMinutes`. Edited under Settings → Notifications → Alert tickets. The API address and key are on the osTicket integration, not here. |
| `nameGenerator` | `themes` — the Generator's server-name lists: `[{ "id", "label", "names": [...], "lastImport"? }]`. Edited under Settings → Names. |
Rows whose key starts with **`_internal:`** are scheduler bookkeeping, not
settings, and aren't part of the app's settings object:
| Key | Value |
|---|---|
| `_internal:secretCheckLastRunDate`, `tailscaleKeyCheckLastRunDate`, `dockerUpdateCheckLastRunDate`, `proxmoxBackupCheckLastRunDate`, `pbsVerificationCheckLastRunDate` | The date a daily check last ran, so a restart doesn't repeat it (or skip it). |
| `_internal:logRetentionLastRunAt` | When the log purge last ran. |
| `_internal:integration_history_since` | When the app first began writing integrations' failing / working-again moments; the uptime ribbons claim nothing earlier for integrations. |
| `_internal:alertTicketsBaselineDone`, `_internal:alertTicketsLastRun` | Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result. |
| `_internal:webPushVapid` | JSON `{publicKey, privateKey}`: the server's own key pair for web push, made the first time it is needed. The private half is encrypted like the other credentials. Replacing it (deleting the row) makes every browser subscribe again. |
| `_internal:healthActiveConditions`, `_internal:automationActiveConditions`, `_internal:endpointActiveConditions` | JSON: the problems currently active (health checks; automation runs; endpoint checks and heartbeats), so each is announced once and again when it clears, and survives a restart. |
| `_internal:flapState` | JSON, by alert key: the recent raises of each alert and whether it is flapping (see NOTIFICATIONS.md), so a restart remembers what is being held. |
| `_internal:unifiSync`, `_internal:homeAssistantSync` | JSON, by integration id: how the last read of each controller or Home Assistant went (`at` is the last *successful* read; one older than twenty minutes is not judged). |
| `_internal:selfBackupLastAttempt` | JSON: how the last attempt to back this database up went (time, whether it worked, why not). |
| `_internal:endpointSuggestionsDismissed`, `_internal:dependencySuggestionsDismissed` | JSON arrays of the suggestion keys somebody said "not that" to. |
| `_internal:metricsRollupBackfilled`, `_internal:endpointHourlyBackfilled` | The time the hourly and daily summaries were first built from the samples already kept (once, after they were added). |
## What happens on delete
| Deleting… | Effect |
|---|---|
| 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, 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. |
| an **integration credential** | The integration / provider using it keeps existing, with `credential_id` cleared. |
| a **user** | Their audit entries stay; `actor_user_id` is cleared and `actor_label` keeps the name. Their personal API tokens and push subscriptions are deleted with them; to-do items and acknowledgements handed to them stay, with the assignee cleared and the name kept. (The app has no way to delete a user: the rules apply to a removal made in the database.) |
| a **Proxmox integration** that servers are linked to | Those servers keep existing and lose their Proxmox link (all four `proxmox_*` columns). The app does this before deleting; the database alone would refuse — see the next section. |
### Soft references (not foreign keys)
These point at other rows by ID or name without the database enforcing it, so
a stale value is possible and the app treats it as "nothing there":
- `maintenance_windows.target_id` (→ a server, integration or DNS provider, by `target_type`)
- `maintenance_aliases.target_id` (the same, by `target_type`)
- `endpoint_checks.server_id` and `heartbeats.server_id` (→ a server), and `patch_plans.integration_id`, `.tags` and `.server_ids` (→ a Semaphore integration, server tags, servers) and `restore_tests.subject_key` (→ a Proxmox guest, by integration and vmid)
- `dependencies.from_id` and `to_id` (→ a server or integration, by their `_type`)
- `audit_log.target_id`
- `dns_records_cache.zone_id` (→ `dns_zones_cache.zone_id`, same provider)
- `servers.tags` (→ `tag_definitions.name`)
- `consistency_ignores.key`
- `notes.target_id` and `todos.target_id` (→ a server or a network device, by `target_type`) and `runbooks.target_id`
- `alert_rules.server_id` (→ a server; a rule for a server that is gone judges nothing)
- `alert_acks.alert_key`, `alert_snoozes.alert_id`, `alert_tickets.alert_key` and `alert_incidents.alert_key` (→ an alert, by its id on the Alerts page: the same problem has the same id)
- `network_devices` ↔ `dependencies` and `maintenance_windows` with `device` as their type (→ `network_devices.id`)
## The Proxmox link's foreign key
`servers.proxmox_integration_id` is meant to clear itself when its integration
is deleted: `schema.ts` says `onDelete: "set null"`. The database doesn't do
that. Migration `0001` added the column as a plain
`REFERENCES integrations(id)`, and SQLite can't change a foreign key afterwards
without rebuilding the table, so the rule *in the database* is **no action**:
with foreign keys on, deleting an integration that a server points at is refused
with `FOREIGN KEY constraint failed`.
The app works around it rather than rebuilding the table. The delete route in
[`server/src/routes/integrations.ts`](server/src/routes/integrations.ts) first
clears the four `proxmox_*` columns on every server linked to that integration,
then deletes it, and the audit entry records how many servers were unlinked
(`unlinkedServers`). Deleting an integration therefore works whether or not
servers are linked to it. Anything that deletes integrations some other way —
a hand-written SQL statement, say — has to do the same first.
## Retention and backups
**Retention.** The two logs, `audit_log` and `diag_log`, are trimmed by the purge job once it is switched on (`logRetention`: off by default, then entries older than `retentionDays`
are deleted), and `notification_queue` is emptied each time the quiet-hours digest is sent. The history tables trim themselves:
| Table | Kept |
|---|---|
| `server_metrics` | 35 days of samples |
| `server_metrics_rollup` | hourly rows 120 days, daily rows about 800 days |
| `endpoint_results` | 14 days of every answer |
| `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 |
| `jellyfin_readings` | 35 days |
| `duplicati_runs` | 400 days, and at most 400 per backup job |
| `heartbeat_pings` | 14 days |
| `alert_incidents`, `incident_notes` | 400 days after the incident resolved |
| `webhook_deliveries` | the newest 100 per webhook, and 14 days |
Settings → Data → Storage shows how big each of these is and whether it is being trimmed as listed here.
Everything else stays until someone deletes it.
**Credentials at rest.** Integration and DNS provider credentials are
encrypted in `integration_credentials` (above). The notification channels'
credentials — the Gotify and ntfy tokens, the SMTP password and the webhook
secret — are in the `settings` rows, and are encrypted in place with the same key:
each is stored as `enc:v1:` followed by the same `iv:authTag:ciphertext` form, and the
rest of the row (URLs, topics, priorities) stays readable. The app decrypts them when
settings are read and encrypts them when they're written, so nothing else sees the
difference.
- A value saved by an older version (plain text) still works, and is encrypted the
next time the server starts.
- Without `CREDENTIALS_ENCRYPTION_KEY`, new notification credentials can only be
stored as plain text, and the server warns about it at startup. They are encrypted
at the next start once the key is set.
- If the key is changed or lost, the stored credentials can't be read: they show as
empty, and the server logs which ones. Enter them again under Settings →
Notifications. Editing a *different* field of the same channel meanwhile doesn't
overwrite the old ciphertext, so putting the right key back restores them.
Everything else in the file — IP addresses, hostnames, secret *names* and expiry
dates, the audit log — is readable by anyone who can read the file, so treat the
file and its backups as sensitive anyway.
**Backups.**
- **Settings → Data → Backup** exports the settings, the integrations and the DNS
providers (with their credentials decrypted, then wrapped in a file encrypted
with a passphrase you choose). Importing merges the settings over the current ones, and adds
integrations and providers that don't exist yet (matched by type and name) — it never
overwrites an existing integration. It does **not** include servers, tasks,
secrets, IP addresses, domains, ports, tags, maintenance windows or logs.
- **A full backup** is a copy of the SQLite file, together with the value of
`CREDENTIALS_ENCRYPTION_KEY` — without that key the stored integration
credentials can't be decrypted. Copy the file while the app is stopped, or take a
snapshot while it runs, so you don't capture it mid-write. [BACKUP.md](BACKUP.md)
has the commands (the container has no `sqlite3` tool), a nightly script, and how to restore.
## Changing the schema
1. Edit [`server/src/db/schema.ts`](server/src/db/schema.ts).
2. From the repo root run `npm run db:generate`; it writes a new numbered SQL
file to `server/drizzle/` (and updates `server/drizzle/meta/`).
3. Read the generated SQL. SQLite can add a column but can't change or drop a
foreign key, so some changes become a table rebuild — which is also why the
[Proxmox link](#the-proxmox-links-foreign-key) described above is the way it is.
4. Start the server (or run `npm run db:migrate`); the migration is applied and
recorded in `__drizzle_migrations`.
5. Commit the schema, the SQL file and the `meta/` changes together, and update
this document.