Both send to one fixed address each (api.telegram.org, api.pushover.net), take part in routing rules and the channel count, have a Send test that shows the service's own refusal, and keep their tokens and keys encrypted and out of errors and the audit log. A Telegram message carries one button, and a Pushover message one link, to the page where an alert can be acknowledged, silenced or snoozed. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
115 KiB
Database schema
Homelab Manager keeps its data in one SQLite file, accessed through
drizzle-orm and the libSQL client. The schema is
defined in one place — 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
- How the tables relate
- Tables
- What's stored inside the JSON columns
- Settings keys
- What happens on delete
- The Proxmox link's foreign key
- Retention and backups
- 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. |
| Writes | SQLite lets one writer in at a time and refuses a second at once ("database is locked"). While a transaction of the app is open, its other writes wait for it (server/src/db/writeGate.ts) rather than being refused — a refused write also leaves its connection unable to commit the next transaction. Reads are never held; a wait over 10 seconds is given up. A lock held by another process (a backup tool reading the file, a second copy of the app) is still refused as before. |
| Migrations | SQL files in server/drizzle/ (0000 … 0085), applied automatically when the server starts. Which ones have run is recorded in the table __drizzle_migrations. |
| Tables | 95 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), 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 AUTOINCREMENTnamedid— exceptsettings, which uses its textkey. - Booleans are
INTEGER0/1 (shown asboolbelow). - Timestamps are text, in two formats, so read them with care:
- Columns the database fills in itself (
created_at, and mostupdated_at) use SQLite'scurrent_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) areYYYY-MM-DD.
- Columns the database fills in itself (
- JSON columns are
TEXTholding JSON; see what's inside. - 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_readingsandstorage_samples(by owner and time),restore_tests,renewals,update_runs,patch_plan_runs,alert_incidents,incident_notes,alert_tickets,runbooksandstatus_items. The other tables have a few thousand rows at most and need none.
How the tables relate
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| download_state : "cascade"
integrations ||--o| hetzner_robot_state : "cascade"
integrations ||--o| adguard_state : "cascade"
integrations ||--o| technitium_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{ server_container_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 24 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: 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, release_cache, port_presets 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 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 |
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 | What this app calls the machine to the rest of the world: what the agent reports, or what an administrator set by hand (see hostname_pinned). |
hostname_pinned |
integer NOT NULL, default 0 | 1 once the hostname was set by hand: a report from the agent then does not replace it. Given up by clearing it, which puts reported_hostname back. |
reported_hostname |
text | What the agent last said its hostname is (kept even while hostname is pinned); null for a server that never reported one. Migration 0082 fills it from hostname for servers that have reported. |
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. |
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).
server_container_ports
The host ports the containers on a server publish, as Dockhand last said: one row per port, replaced for a server each time its Docker host is read on the health pass (the Docker host is matched to a server by its name there, as Uptime Kuma targets are). It only names a port — on the Ports pages (ahead of a port preset's name, behind a label somebody wrote) and in the new-port alert — and is never copied into server_ports, so it does not make a port "expected". A host Dockhand can't read keeps its rows; rows not refreshed for a day are ignored and deleted.
| Column | Type | Notes |
|---|---|---|
id |
integer PK | |
server_id |
integer NOT NULL → servers.id, cascade |
|
port |
integer NOT NULL | The port on the host. |
protocol |
text NOT NULL, default tcp |
tcp |
container |
text NOT NULL | The container's name. |
image |
text NOT NULL, default '' |
Its image, for the hover text. |
updated_at |
text NOT NULL | ISO; when it was last read. |
Unique index server_container_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 |
port_presets
A named list of ports ("Remote access": SSH, RDP, VNC). A port in any preset is named wherever it is shown, can be scanned for on many servers at once, and can have its name written onto the servers where it is open (server_ports.label). The ready-made ones are written once, into an empty table (flag _internal:portPresetsSeeded in settings), and are ordinary rows after that.
| Column | Type | Notes |
|---|---|---|
id |
integer PK | |
name |
text NOT NULL, unique | Compared without regard to case by the API. |
ports |
text NOT NULL, default [] |
JSON: [{ "port": 3389, "protocol": "tcp", "label": "RDP" }]; 1–60 entries, no port + protocol twice. |
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.
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.
| 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): 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: the same kinds, or internet (id 1). The internet is not a row anywhere — it is added to the graph in code, always, is never down, and is never the thing that 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. |
cost_item_versions
What an item of cost_items was at each time — the Costs page's history. One row for each stretch in which its name, amount, currency, period and kind were what they are: opened when the item is added or any of those change, closed (valid_to) when they change again or the item is removed. A change of only the note or the billing day makes no row. item_id is a soft reference (no foreign key): the rows stay when the item is removed, which is the point. Kept in step with cost_items by services/costHistory.ts whenever an item is saved and every six hours; an item that was there before the table existed is given a row from its created_at, at the amount it has now.
| Column | Type | Notes |
|---|---|---|
id |
integer PK | |
item_id |
integer NOT NULL | The item. Index cost_item_versions_item_idx. |
name, currency, period, category |
text NOT NULL | As they were. |
amount |
real NOT NULL | As it was, per period, with VAT. |
valid_from |
text NOT NULL | ISO. For an item's first row, when it was added. |
valid_to |
text | ISO; null while it is in force. |
cost_snapshots
What can be read rather than typed — a Hetzner project's monthly estimate — as it was on each day, written once a day (a second time the same day replaces the first). The estimate moves with the servers and cannot be worked out afterwards. Primary key (day, key).
| Column | Type | Notes |
|---|---|---|
day |
text NOT NULL | YYYY-MM-DD (UTC). |
key |
text NOT NULL | The source: hetzner:<integration id>. Kept after the integration is removed. |
name, currency |
text NOT NULL | The project's name and the currency as they were. |
monthly |
real NOT NULL | Per month, with VAT, at list prices. |
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.
download_state
How a qBittorrent or SABnzbd (an integration of type qbittorrent or sabnzbd) 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, plus since when it has been paused, disconnected or idle with work waiting — which only this app can know, and which is carried from read to read.
| Column | Type | Notes |
|---|---|---|
integration_id |
integer PK | |
version |
text | |
speed_down, speed_up |
integer | Bytes per second; null when not said (SABnzbd does not say its upload speed). |
paused |
integer (boolean) NOT NULL, default false | The whole queue is paused (SABnzbd). |
connection |
text | connected, firewalled or disconnected (qBittorrent); null for SABnzbd or when not said. |
counts |
text NOT NULL | JSON: how many items are in each state — all of them, not just the ones listed. |
total |
integer NOT NULL, default 0 | How many items there are. |
items |
text NOT NULL, default [] |
JSON: the items that are not finished and idle (seeding and stopped ones are only counted), the ones with something to say first, at most 100. |
failed |
text | JSON: downloads that failed (SABnzbd's history, the last 50 entries); null when not said or could not be read. |
disks |
text | JSON: label, free bytes and total bytes (null where the client does not say how big the disk is); null when it could not be read. |
warnings |
text | JSON { count, recent }: SABnzbd's own list of warnings; null when not read. |
since |
text NOT NULL, default {} |
JSON { pausedSince, disconnectedSince, idleSince }: the time of the first read that showed each; null while it is not so. |
updated_at |
text NOT NULL | ISO. |
How the last read went is kept in settings, key _internal:downloadsSync.
hetzner_robot_state
How a Hetzner Robot account (an integration of type hetznerrobot) is right now, one row each, replaced at every read (every fifteen 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, plus, for each server, since when its rescue system has been on and since when it has not been "ready" — which only this app can know, and which is carried from read to read by server number.
| Column | Type | Notes |
|---|---|---|
integration_id |
integer PK | |
servers |
text NOT NULL, default [] |
JSON: each dedicated server — number, name, addresses, product, data centre, traffic plan, status, cancelled, paid until, rescue system on (null when it could not be asked), rescueSince, notReadySince. |
storage_boxes |
text | JSON: each storage box — id, name, login, product, location, cancelled, locked, paid until, linked server. Null when they could not be read. |
skipped_detail |
integer NOT NULL, default 0 | How many servers were not asked about their rescue system (more than 25, to stay under Robot's request limit). |
updated_at |
text NOT NULL | ISO. |
How the last read went is kept in settings, key _internal:hetznerRobotSync.
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.
technitium_state
How a Technitium DNS Server (an integration of type technitium) 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 | |
started_at |
text | ISO: when the DNS server last started (from its uptimestamp); null when it did not say. |
dns_port |
integer NOT NULL, default 53 | The port of its first listening endpoint. |
blocking_enabled |
integer NOT NULL, default 1 | Whether blocking is on. |
blocking_off_since |
text | ISO: the first read that showed blocking off; null while it is on. |
settings |
text NOT NULL | JSON: { blockLists: { count, intervalHours, nextUpdate }, cacheMaximumEntries, recursion, dnssecValidation }. |
stats, zones, dhcp |
text | JSON: the last day's statistics (queries and how they ended, counts, the clients and names asked about most) · { total, disabled, issues: [{ name, problem }] } · { scopes, enabledScopes, leases }. Null when they could not be read (dhcp also when there is no DHCP server). |
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:technitiumSync.
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.
release_cache
The newest release of each application there is a connected integration for, as GitHub last said — only while Operations → App versions is switched on. One row for each repository (owner/name); no foreign keys.
| Column | Type | Notes |
|---|---|---|
repo |
text PK | |
tag |
text NOT NULL | The release's tag as published (v4.0.9.2244); empty when none has been found. |
published_at |
text | ISO. |
url |
text | The release's page. |
checked_at |
text NOT NULL | ISO: when it was last looked up. |
error |
text | Why the last lookup failed; null when it worked. The tag it had is kept. |
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 (Alert settings → 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 (Alert settings → 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, Telegram, Pushover, 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, telegram, pushover, smtp, webhook |
The notification channels (beside webPush): enabled, address or chat, and credentials (token / keys / password / secret). Telegram has no address (it is always api.telegram.org): token, chatId, silent; Pushover (api.pushover.net): appToken, userKey, device, priority (-2 to 2). The credential fields are stored encrypted (prefix enc:v1:) — see 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). |
versionChecks |
enabled (false) — whether the newest release of each connected application is looked up on GitHub — and alertAfterDays (0 = never): after how many days a newer release is a warning. |
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 Alert settings → 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_container_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, bytarget_type)maintenance_aliases.target_id(the same, bytarget_type)endpoint_checks.server_idandheartbeats.server_id(→ a server), andpatch_plans.integration_id,.tagsand.server_ids(→ a Semaphore integration, server tags, servers) andrestore_tests.subject_key(→ a Proxmox guest, by integration and vmid)dependencies.from_idandto_id(→ a server or integration, by their_type)audit_log.target_iddns_records_cache.zone_id(→dns_zones_cache.zone_id, same provider)servers.tags(→tag_definitions.name)consistency_ignores.keynotes.target_idandtodos.target_id(→ a server or a network device, bytarget_type) andrunbooks.target_idalert_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_keyandalert_incidents.alert_key(→ an alert, by its id on the Alerts page: the same problem has the same id)network_devices↔dependenciesandmaintenance_windowswithdeviceas 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 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, ntfy and Telegram tokens, the two Pushover keys, 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 has the commands (the container has nosqlite3tool), a nightly script, and how to restore.
Changing the schema
- Edit
server/src/db/schema.ts. - From the repo root run
npm run db:generate; it writes a new numbered SQL file toserver/drizzle/(and updatesserver/drizzle/meta/). - 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 described above is the way it is.
- Start the server (or run
npm run db:migrate); the migration is applied and recorded in__drizzle_migrations. - Commit the schema, the SQL file and the
meta/changes together, and update this document.