Files
Homelab-manager/DATABASE.md
T
bobbanandClaude Sonnet 5.5 672c7f2f66 Let an administrator set a server's hostname by hand
A Change link on the Identity card sets the hostname (a host name or an
address, written lower case without the trailing dot). It is then kept even
when the agent reports another — marked "set by hand", with what the agent
reports shown beside it — until "Use what the agent reports" gives it up. The
agent's own hostname is always remembered (reported_hostname). PUT and DELETE
/api/servers/:id/hostname, administrators only, audited with from and to.
Migration 0082 adds hostname_pinned and reported_hostname and fills the latter
for servers that have reported. It changes this app's name for the server, not
the machine's.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-01 23:30:31 +01:00

109 KiB
Raw Blame History

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

File DATABASE_PATH, default ../data/homelab-manager.sqlite (relative to server/; /app/data/... in Docker). The folder is created if missing.
Foreign keys Switched on for every connection (PRAGMA foreign_keys = ON), so the ON DELETE rules below are enforced.
Migrations SQL files in server/drizzle/ (0000 … 0082), applied automatically when the server starts. Which ones have run is recorded in the table __drizzle_migrations.
Tables 91 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 AUTOINCREMENT named id — except settings, which uses its text key.
  • Booleans are INTEGER 0/1 (shown as bool below).
  • Timestamps are text, in two formats, so read them with care:
    • Columns the database fills in itself (created_at, and most updated_at) use SQLite's current_timestamp: 2026-10-03 14:05:09, UTC, with no zone marker. Treat it as UTC, not local time.
    • Columns the app fills in (last_seen_at, last_login_at, synced_at, last_checked_at, …) use ISO 8601: 2026-10-03T14:05:09.123Z.
    • Dates without a time (secrets.expiry_date, domains.expires_at) are YYYY-MM-DD.
  • JSON columns are TEXT holding JSON; see what's inside.
  • Enumerations (roles, types) are plain text — SQLite doesn't enforce the allowed values; the app does.
  • Indexes: besides primary keys and the unique ones listed per table, a few plain indexes serve the tables that are read by range or by what they are about: endpoint_results, heartbeat_pings, server_metrics, ha_readings, ups_readings and storage_samples (by owner and time), restore_tests, renewals, update_runs, patch_plan_runs, alert_incidents, incident_notes, alert_tickets, runbooks and status_items. The other tables have a few thousand rows at most and need none.

How the tables relate

erDiagram
    users ||--o{ audit_log : "actor (set null)"
    users ||--o{ push_subscriptions : "cascade"
    endpoint_checks ||--o{ endpoint_results : "cascade"
    heartbeats ||--o{ heartbeat_pings : "cascade"
    integration_credentials ||--o{ integrations : "credential (set null)"
    users ||--o{ api_tokens : "cascade"
    servers ||--o{ server_metrics_rollup : "cascade"
    endpoint_checks ||--o{ endpoint_hourly : "cascade"
    integrations ||--o{ network_devices : "cascade"
    integrations ||--o{ network_segments : "cascade"
    integrations ||--o{ network_server_links : "cascade"
    integrations ||--o{ ha_watched : "cascade"
    integrations ||--o{ storage_series : "cascade"
    storage_series ||--o{ storage_samples : "cascade"
    integrations ||--o{ ha_entities : "cascade"
    integrations ||--o{ ha_readings : "cascade"
    integrations ||--o| ups_state : "cascade"
    integrations ||--o{ ups_readings : "cascade"
    integrations ||--o| jellyfin_state : "cascade"
    integrations ||--o| authentik_state : "cascade"
    integrations ||--o| prometheus_state : "cascade"
    integrations ||--o| immich_state : "cascade"
    integrations ||--o| nextcloud_state : "cascade"
    integrations ||--o{ dockhand_vulnerabilities : "cascade"
    integrations ||--o| hetzner_state : "cascade"
    integrations ||--o| fragnet_state : "cascade"
    integrations ||--o| arr_state : "cascade"
    integrations ||--o| adguard_state : "cascade"
    integrations ||--o| 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.

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.

Which server is plugged into which network device, worked out on every UniFi read: a client the controller lists whose IP address is exactly one server's own. Replaced as a whole on a read that lists any clients; kept as it was when it lists none.

Column Type Notes
id integer PK
integration_id integer NOT NULL → integrations.id, cascade Unique together with server_id and client_mac.
server_id integer NOT NULL → servers.id, cascade
device_external_id text NOT NULL The MAC of the switch or access point (network_devices.external_id).
client_mac text NOT NULL The server's own MAC as the controller sees it.
port integer The switch port, where the controller says.
wired bool NOT NULL False for a client on Wi-Fi.
updated_at text NOT NULL ISO.

network_segments

The networks (VLANs) and Wi-Fi names of a UniFi controller, replaced as a whole on every read. Passphrases are never stored.

Column Type Notes
id integer PK
integration_id integer NOT NULL → integrations.id, cascade Unique together with kind and external_id.
kind text NOT NULL network | ssid.
external_id, site_name, name text
enabled bool NOT NULL
vlan_id integer
subnet, purpose text A network's address range and what it is for.
security, network_name text A Wi-Fi name's security, and the network its clients land on.
updated_at text NOT NULL ISO.

notes

A free-text note about a server or a network device.

Column Type Notes
id integer PK
target_type, target_id text, integer NOT NULL server or device, and its id. Unique together: one note each. Not a foreign key (a removed thing's note is ignored).
body text NOT NULL The text, with the small formatting runbooks use. Saving an empty one deletes the row.
updated_by text Who last saved it, as a name.
updated_at text NOT NULL ISO.

note_photos

A photo on the note of a server or a network device — up to 12 each. The picture itself is in the row, so a database backup has it. Exactly one of server_id and device_id is set; both are foreign keys with cascade, so removing the server or the device removes its photos; each is indexed.

Column Type Notes
id integer PK
server_id, device_id integer The server or the device it is on.
content_type text NOT NULL image/jpeg, image/png, image/gif or image/webp — told from the bytes when it was added, never from what the upload said.
data blob NOT NULL The picture, up to 4 MB (the browser makes it far smaller first).
size integer NOT NULL Bytes.
caption text Up to 120 characters.
created_by text As a name.
created_at text NOT NULL ISO.

todos

The small jobs of Operations → To do.

Column Type Notes
id integer PK
title text NOT NULL
detail text
due_date text YYYY-MM-DD. A job with a day, while open, is on the Coming up calendar.
assignee_user_id integer → users.id, set null Who it is handed to.
assignee_name text Their name when it was handed over, so it still reads if they are removed.
target_type, target_id text, integer server or device, and its id, when the job is about one. Not a foreign key.
created_by, created_at text
done_at, done_by text ISO and a name; null while open.

ha_watched

The Home Assistant entities somebody chose to watch (see INTEGRATIONS.md).

Column Type Notes
id integer PK
integration_id integer NOT NULL → integrations.id, cascade The Home Assistant. Unique together with entity_id.
entity_id text NOT NULL sensor.ups_battery.
name text What to call it here; the entity's own friendly name when null.
above, below real Limits for a numeric value: an alert when it is over above or under below.
created_at text NOT NULL ISO.

ha_entities

What the last read said about each watched entity. Primary key (integration_id, entity_id); integration_id is a foreign key with cascade. Rows of an entity no longer watched are removed on the next read.

Column Type Notes
friendly_name, unit, device_class text
state text NOT NULL As Home Assistant says it; missing when it is no longer in Home Assistant at all.
value real The state as a number, when it is one.
last_changed text ISO, from Home Assistant.
unavailable_since text ISO. When it was first seen unavailable, unknown or missing; kept until it speaks again. The alert counts from here.
updated_at text NOT NULL ISO.

ha_readings

A numeric value of a watched entity at a moment, for the chart: one at most every two minutes, deleted after 35 days. integration_id is a foreign key with cascade; (integration_id, entity_id, at) is indexed.

Column Type Notes
id integer PK
entity_id text NOT NULL
at text NOT NULL ISO.
value real NOT NULL

ups_state

How a UPS (an integration of type ups) is right now, one row each, replaced at every read (every minute). integration_id is the primary key and a foreign key with cascade.

Column Type Notes
integration_id integer PK → integrations.id.
model, manufacturer text As the UPS says.
status_text text NOT NULL The UPS's own words (OL CHRG, on battery, battery normal).
on_battery, low_battery, replace_battery, overload bool NOT NULL, default 0 Mains power lost; battery nearly empty; battery to be replaced; overloaded.
charge, load_percent real Percent.
runtime_seconds integer How long the battery would last at the present load.
input_voltage, output_voltage real Volts.
on_battery_since text ISO; when mains power was lost, kept until it is back.
updated_at text NOT NULL ISO; the last read that worked.

How the last read went (and when it last worked) is in settings under the internal key upsSync, like the Home Assistant sync's.

ups_readings

A UPS at a moment, for the charts: one every five minutes, and every minute while it runs on battery (or when that changes), deleted after 35 days. integration_id is a foreign key with cascade; (integration_id, at) is indexed.

Column Type Notes
id integer PK
at text NOT NULL ISO.
charge, load_percent, input_voltage real
runtime_seconds integer
on_battery bool NOT NULL, default 0

nextcloud_state

How a Nextcloud (an integration of type nextcloud) is right now, one row each, replaced at every read (every five minutes). integration_id is the primary key and a foreign key with cascade. There is no history table.

Column Type Notes
integration_id integer PK
version text
maintenance, needs_upgrade bool NOT NULL, default 0 From status.php.
detail bool NOT NULL, default 0 Whether the monitoring app answered (an administrator's app password is needed).
free_bytes, users, files, active_24h, app_updates integer Null when the monitoring app was not asked or did not say.
core_update text The version Nextcloud says is available (newer when it says only that there is one); null when none is, or not asked.
cron_state, cron_text text Nextcloud's own Cron last run check: success, info, warning or error, and what it said. Null when it could not be asked (no login, or before Nextcloud 28) — not the same as fine.
setup_issues text JSON: name, severity (error or warning), text — its other setup checks that report a problem, at most 40. Null when the checks could not be asked.
updated_at text NOT NULL ISO.

dockhand_vulnerabilities

What Dockhand's own stored vulnerability scans add up to for each of its Docker hosts (its environments), as last read — one row for each Dockhand integration and environment, replaced at every read (every fifteen minutes; a host Dockhand no longer lists is dropped). integration_id is a foreign key with cascade; the primary key is (integration_id, environment_id). Nothing is scanned by this app — it reads only what Dockhand kept.

Column Type Notes
integration_id integer PK
environment_id integer PK Dockhand's own id for the Docker host.
environment_name text NOT NULL
critical, high, medium, low integer The counts across the host's scanned images. Null when the count could not be read (an older Dockhand, a host it cannot reach) — which is not the same as 0.
images_scanned, total_images integer How many of the host's images have a scan; the rest are not known to be clean.
findings text NOT NULL, default [] JSON: the critical findings (CVE, package, installed and fixed version, image, the containers that use it), at most 100.
images, images_at text JSON: the images this host's running containers use, each with when it was built (image, created, containers), and when that was read (migration 0076). Null: never read, or could not be.
updated_at text NOT NULL ISO.

How the last read went is kept in settings, key _internal:dockerVulnSync.

netbox_state

How a NetBox (an integration of type netbox) is right now, one row each, replaced at every read (every five minutes). integration_id is the primary key and a foreign key with cascade.

Column Type Notes
integration_id integer PK
version text
workers_running integer How many RQ workers; null when /status/ did not say (which is not the same as 0).
devices, virtual_machines, prefixes, ip_addresses integer Counts; null when not read.
ips text JSON array of the addresses NetBox holds, without the prefix length, at most 5000; null when they could not be listed.
updated_at text NOT NULL ISO.

speedtest_results

The speed tests a Speedtest Tracker (an integration of type speedtest) has made, one row each, kept for 90 days. The primary key is (integration_id, result_id) and integration_id is a foreign key with cascade; an index on (integration_id, at). A result is stored once under Speedtest Tracker's own id and never changed afterwards. How the last read went is kept in settings, key _internal:speedtestSync.

Column Type Notes
integration_id, result_id integer PK result_id is Speedtest Tracker's own id for the result.
at text NOT NULL ISO: when the test was made (the time Ookla gives, else created_at taken as UTC).
status text NOT NULL completed, failed, skipped …
download_bps, upload_bps real Bits per second; null for a test that has none (failed, skipped).
ping_ms real Milliseconds.
healthy bool Speedtest Tracker's own judgement by its thresholds; null when it did not say.

cost_items

Things paid for by hand (a domain, a VPN, a licence, a subscription), one row each — the Costs page. What can be read (a Hetzner project's estimate) is not here. No foreign keys.

Column Type Notes
id integer PK
name text NOT NULL
amount real NOT NULL What is paid each time, with VAT.
currency text NOT NULL Three capital letters. Totals are per currency; none is converted.
period text NOT NULL month or year.
category text NOT NULL, default Other Free text (Hosting, Domains, Subscriptions …).
renews_on text YYYY-MM-DD: a day it is (or will first be) billed. An anchor: the next time it falls is worked out from it and shown in Coming up.
note text
created_at, updated_at text NOT NULL ISO.

hetzner_state

How a Hetzner Cloud project (an integration of type hetzner; a token belongs to one project) is right now, one row each, replaced at every read (every five minutes). integration_id is the primary key and a foreign key with cascade. There is no history table.

Column Type Notes
integration_id integer PK
servers text NOT NULL, default [] JSON: each server as read (status, type, location, addresses, traffic this month and included, rescue mode, backup window, monthly price) plus what the app has seen of it between reads: lastRunningAt, statusSince, rescueSince. Hetzner does not say when a server went off; these are the times of the reads that showed it.
volumes, images text JSON; the volumes, and the snapshots and backups. Null when they could not be asked — which is not the same as none.
cost text JSON: the monthly estimate at list prices including VAT (currency, servers, backups, volumes, snapshots, IPs, load balancers, floating IPs, total). Null when the price list could not be read.
load_balancers, floating_ips, certificates text JSON: each load balancer with the health of its targets, each floating IP and what it points at, each certificate with when it ends. Null when they could not be asked. (Migration 0072.)
updated_at text NOT NULL ISO.

How the last read went is kept in settings, key _internal:hetznerSync.

fragnet_state

How a Fragnet game panel account (an integration of type fragnet; an API key belongs to one account) is right now, one row each, replaced at every read (every five minutes). integration_id is the primary key and a foreign key with cascade. There is no history: what is stored is the last good read.

Column Type Notes
integration_id integer PK
servers text NOT NULL, default [] JSON: each game server as read (the panel's short id, name, game, addresses, SFTP, limits, running state, what it uses, backups, schedules, database count) plus what the app has seen of it between reads: stateSince and firstSeenAt. A part that could not be read (backups, schedules, databases, usage) is null — which is not the same as none.
updated_at text NOT NULL ISO.

How the last read went is kept in settings, key _internal:fragnetSync.

arr_state

How a Sonarr, Radarr or Prowlarr (an integration of type sonarr, radarr or prowlarr) is right now, one row each, replaced at every read (every five minutes). integration_id is the primary key and a foreign key with cascade. There is no history: what is stored is the last good read.

Column Type Notes
integration_id integer PK
version text
health text NOT NULL, default [] JSON: what its own checks found (source, type, message).
queue text JSON { total, items }: how many downloads there are and the first hundred (title, status, how it is judged, what it says is wrong, size, when it was added, client, indexer). Null when it could not be read — and always for Prowlarr, which has none.
disks text JSON: path, free and total bytes; null when it could not be read.
missing integer Wanted items with no file (Sonarr, Radarr); null when not read.
indexers text JSON, Prowlarr only: each indexer and, if Prowlarr has switched it off after failures, until when.
updated_at text NOT NULL ISO.

How the last read went is kept in settings, key _internal:arrSync.

adguard_state

How an AdGuard Home (an integration of type adguard) is right now, one row each, replaced at every read (every two minutes). integration_id is the primary key and a foreign key with cascade. No history: what is stored is the last good read, plus two clocks only this app can keep.

Column Type Notes
integration_id integer PK
version text
running, protection_enabled integer NOT NULL, default 1 Whether its DNS server runs; whether protection is on.
protection_off_since text ISO: the first read that showed protection off; null while it is on.
dns_port integer NOT NULL, default 53
stats, filters text JSON: the statistics (queries, blocked, average time, top names and clients) and the filter lists (name, on or off, rules, when updated). Null when they could not be read.
probe text JSON: the real DNS question — { ok, ms, error, name, host }.
probe_fail_since text ISO: the first read in which the question went unanswered; null while it is answered.
updated_at text NOT NULL ISO.

How the last read went is kept in settings, key _internal:adguardSync.

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 (Monitoring → Service levels): what a thing is held to, measured over calendar months. No foreign keys: the thing measured is a plain reference, and a target whose subject is removed is shown as having nothing to measure.

Column Type Notes
id integer PK
name text NOT NULL
subject_type text NOT NULL endpoint (an endpoint check), server or integration.
subject_id integer NOT NULL The id of that thing.
target real NOT NULL Percent, 90 to 99.999.
alert bool NOT NULL, default 1 Warn at 80 % of the month's error budget, and when it is overspent.
created_by text
created_at text NOT NULL

Nothing about how a target is doing is stored: it is worked out when asked, from endpoint_daily and the audit log.

duplicati_sources

A machine running Duplicati that reports to this app. token_hash is the SHA-256 of the secret in its address (shown once, never stored); server_id is a plain reference to the server it runs on (maintenance on it silences the alerts).

Column Type Notes
id integer PK
name text NOT NULL
token_hash text NOT NULL, unique
token_prefix text NOT NULL The first characters, to tell addresses apart.
server_id integer
created_by, created_at text
last_report_at text ISO; the last time anything arrived.

duplicati_backups

One backup job of one source, as its last report left it; learned from a first report, by name (unique with source_id). source_id is a foreign key with cascade.

Column Type Notes
id integer PK
source_id, name integer, text
last_report_at, last_begin, last_end text ISO.
last_result text Success, Warning, Error or Fatal.
duration_seconds, examined_files, size_bytes, added_files, modified_files, deleted_files integer As the last report said; null when it did not.
warnings, errors integer NOT NULL, default 0
message text The first error, or warning.
last_success_at text ISO; a run with warnings counts.
consecutive_failures integer NOT NULL, default 0 Critical from 2.
expected_hours integer NOT NULL, default 48 How long it may go without succeeding.
alert bool NOT NULL, default 1

duplicati_runs

Each report of a backup, for its history: 400 days and at most 400 per job. backup_id is a foreign key with cascade; (backup_id, at) is indexed.

Column Type Notes
id integer PK
at text NOT NULL ISO; when the backup finished.
result text NOT NULL
duration_seconds, size_bytes, files_changed integer
warnings, errors integer NOT NULL, default 0

alert_rules

Limits of the administrator's own (Monitoring → Alert rules), judged for the servers they cover on the health pass; what they find is ordinary health conditions keyed rule:<id>:server:<server>[:<disk>].

Column Type Notes
id integer PK
name text NOT NULL Shown in the alert's message, in square brackets.
enabled bool NOT NULL, default 1
metric text NOT NULL cpu, mem, disk (use, percent) or disk_temp (°C, from the SMART report).
mount text For disk: one mount point or drive; null = every disk.
operator text NOT NULL, default above above or below.
threshold real NOT NULL Percent (0–100), or °C (0–150).
for_minutes integer NOT NULL, default 0 How long every sample must have been past the limit (0–1440); always 0 for disk_temp.
severity text NOT NULL, default warning warning or critical.
server_id integer One server. A plain reference, not a foreign key: a rule for a server that is gone judges nothing. Not together with tag.
tag text Servers with this tag; with a null server_id too, every server.
created_by, created_at text

storage_series

A pool an integration reports — a Proxmox storage or root filesystem, a Synology volume — so that it can be forecast (see README, Forecasts for Proxmox storage and Synology volumes).

Column Type Notes
id integer PK
integration_id integer NOT NULL → integrations.id, cascade Unique together with key.
key text NOT NULL <node>:storage:<id>, shared:<id>, <node>:rootfs (Proxmox) or volume:<id> (Synology).
label text NOT NULL What to call it in a message.
latest_percent real NOT NULL The newest reading.
used_bytes, total_bytes integer
updated_at text NOT NULL ISO; a pool not reported for 30 days is deleted.

storage_samples

One reading of a pool an hour at most, kept 400 days. series_id is a foreign key with cascade; (series_id, at) is indexed.

Column Type Notes
id integer PK
at text NOT NULL ISO.
value real NOT NULL Percent used.

alert_snoozes

An alert hidden until a time (see README, Snooze). Keyed like alert_acks, by the alert's id on the Alerts page; no foreign keys.

Column Type Notes
id integer PK
alert_id text NOT NULL, unique
condition_key text NOT NULL The key behind it, which the notifications carry (so they can be held).
message text NOT NULL What it said when it was snoozed.
until text NOT NULL ISO. When it has passed, an alert that is still there is announced again and the row is deleted. A closed alert has 9999-12-31T00:00:00.000Z, which never comes.
kind text NOT NULL, default snooze snooze, or closed ("dealt with or accepted": hidden with no end, until it gets more serious than severity or has been gone for 30 minutes).
severity text For a closed alert: critical, warning or info as it was when it was closed.
note text For a closed alert: why. (It is also written on the incident.)
snoozed_by, snoozed_at text NOT NULL
last_seen_at text NOT NULL ISO; the last time the alert was there. A row whose alert has been gone for 30 minutes is deleted.

push_subscriptions

A browser or phone that asked for push notifications, one row per device.

Column Type Notes
id integer PK
user_id integer NOT NULL → users.id, deleted with the user.
endpoint text NOT NULL, unique The address of the browser's push service. It is a secret: with the keys below it can write to that device.
p256dh, auth text NOT NULL The browser's public key and authentication secret, which every message is encrypted with.
label text What the person calls it, or the browser it is.
created_at text NOT NULL ISO.
last_success_at text When the push service last accepted a message for it.
min_severity text warning or critical: this browser only wants alerts at least that bad. Null = every severity.
categories text JSON array of the kinds of alert it wants (offline, disk, …). Null = every kind.

A subscription is removed when the push service says it is gone (HTTP 404 or 410), when its owner or an administrator removes it, and all of them are removed if the server's own key pair has to be made again.

endpoint_checks

A web address, TCP port or TLS certificate the app asks about every few minutes (see the README). The last answer is kept on the row.

Column Type Notes
id integer PK
name text NOT NULL
kind text NOT NULL http, tcp or tls.
target, port text NOT NULL, integer http: the address. tcp and tls: the host, and the port.
expect_status, keyword text http only: the good status codes (200-204, 401; null = 200–399) and a word the page must contain.
value_path, value_op, value_expected, value_unit text http only: judge a value in a JSON answer — where it is (data.result[0].value[1]), how it must compare (< <= > >= = != contains exists), what to, and a unit to show. All null for a check that judges no value.
header_name, header_value text http only: a header sent with the request. The value is stored encrypted (enc:v1:) when an encryption key is set, and is never returned by the API.
last_value text What a value check read the last time.
insecure bool NOT NULL, default 0 Accept a certificate that isn't trusted (its expiry is still watched).
interval_minutes, timeout_seconds, failures_before_alert, warn_days integer NOT NULL Defaults 5, 10, 2 and 14.
server_id integer The server it is about. A plain reference, not a foreign key: maintenance on that server silences the check's alerts; one whose server is gone is just unlinked.
enabled bool NOT NULL, default 1
last_checked_at, last_ok, last_message, last_response_ms text, bool, text, integer How the latest ask went.
cert_expires_at text ISO; when the certificate it showed runs out.
consecutive_failures integer NOT NULL, default 0 A problem once this reaches failures_before_alert.
last_change_at text When it last went from working to failing or back.
created_at text NOT NULL

endpoint_results

One row per answer, kept for two weeks: uptime, average answer time and the run of recent results come from these.

Column Type Notes
id integer PK
check_id integer NOT NULL → endpoint_checks.id, deleted with it (indexed with at).
at text NOT NULL ISO.
ok bool NOT NULL
ms, message integer, text
value real The number a value check read, when it is one; what the value chart is drawn from.

heartbeats

A job that reports in: it calls /api/heartbeat/<token> when it finishes, and the app speaks up when the call doesn't come in time (services/heartbeats.ts).

Column Type Notes
id integer PK
name text NOT NULL
token text NOT NULL, unique The secret part of the address (hb_…). Kept as it is, not hashed, because the address has to be shown again; all it allows is "I'm alive".
period_minutes, grace_minutes integer NOT NULL How often it should report, and how much later is still fine (default 10).
server_id integer Soft reference to the server it runs on, so its maintenance silences the alerts.
enabled bool NOT NULL, default true A switched-off heartbeat still takes calls.
notes text
last_ping_at, last_status text When the last call that ended a run came in, and ok or fail.
last_message, last_duration_ms text, integer The note sent with it, and how long the run took when it said it had started.
last_start_at text ISO; the last /start call.
ping_count, created_at integer, text

heartbeat_pings

The recent calls to each heartbeat, for its history; kept two weeks.

Column Type Notes
id integer PK
heartbeat_id integer NOT NULL → heartbeats.id, deleted with it (indexed with at).
at text NOT NULL ISO.
kind text NOT NULL ok, fail or start.
duration_ms, message integer, text

restore_tests

Each time somebody tried to restore a backup, and how it went. History is kept; the newest per subject is what counts.

Column Type Notes
id integer PK
subject_key text NOT NULL guest:<integration id>:<vmid> for a Proxmox guest, custom:<name> for anything else. Not a foreign key (indexed with tested_at).
label text NOT NULL What to call it.
tested_at text NOT NULL YYYY-MM-DD.
result text NOT NULL ok, partial, failed or not_needed.
note, tested_by text
created_at text NOT NULL

metrics_tokens

Read-only access to /metrics for Prometheus. Only a hash of each secret is stored.

Column Type Notes
id integer PK
label text NOT NULL
token_hash text NOT NULL, unique SHA-256 of the secret, which is shown once and never stored.
token_prefix text NOT NULL The first characters, to tell tokens apart in the list.
created_by text
created_at text NOT NULL
last_used_at text ISO; updated at most once a minute.

event_webhooks

URLs sent a signed JSON message when an alert begins or ends or maintenance starts or finishes.

Column Type Notes
id integer PK
label text NOT NULL
url text NOT NULL http or https, with no user name or password in it.
secret text Signs each message (HMAC-SHA256). Stored encrypted (enc:v1:) when an encryption key is set; never returned by the API.
events text NOT NULL JSON array of alert.opened, alert.resolved, maintenance.started, maintenance.ended.
enabled bool NOT NULL, default 1
created_by text
created_at text NOT NULL
last_attempt_at, last_result text When it was last sent to and what came back (200, or what went wrong).

webhook_deliveries

The log of what was sent to each event webhook (Settings → API and webhooks → Sent): one row per message, with its second try counted in. Trimmed to the newest 100 per webhook and 14 days each time one is added.

Column Type Notes
id integer PK
webhook_id integer NOT NULL FK → event_webhooks.id, cascade. Indexed with created_at.
event text NOT NULL alert.opened …
delivery_id text NOT NULL The message's id and X-HLM-Delivery; a resend keeps it.
attempts integer NOT NULL, default 1 2 when the first try failed.
ok bool NOT NULL Whether a 2xx came back.
result text NOT NULL 200, or what went wrong.
body text NOT NULL The JSON that was sent, cut at 16 001 characters (longer than 16 000 means it cannot be sent again).
retry_of integer The id of the delivery this one sent again by hand.
created_at text NOT NULL ISO.

Addresses that open a read-only page without signing in (Settings → Share links): the wall display, or a status page. Only a hash of the secret is stored.

Column Type Notes
id integer PK
label text NOT NULL What it is for, e.g. "Hall TV".
token_hash text NOT NULL, unique SHA-256 of the secret in the address; the secret itself is shown once and never stored.
token_prefix text NOT NULL The first characters of the secret, to tell links apart in the list.
detail text NOT NULL, default summary For a wall: summary (numbers only) or names (also the names of what is wrong, in maintenance, and the integrations). Not used by a status page.
kind text NOT NULL, default wall wall, status or calendar (an iCalendar feed of what is coming up; detail says whether it carries names). Each kind's address opens only that kind.
title, message text A status page's heading and its optional message; null for a wall.
created_by text The administrator's name at the time.
created_at text NOT NULL
expires_at text ISO; null = until removed.
last_used_at text ISO; updated at most once a minute.

status_items

What a status page shows, in order.

Column Type Notes
id integer PK
link_id integer NOT NULL → share_links.id, deleted with the link.
position integer NOT NULL Order on the page (indexed with link_id).
label text NOT NULL The name people will recognise — the only thing about it the public sees.
kind text NOT NULL server, integration or monitor.
target_id integer NOT NULL The server, the integration, or the Uptime Kuma a monitor belongs to. A plain reference, not a foreign key: if it is removed the item reads "can't tell".
monitor_id text Uptime Kuma's own id for the monitor (kind = monitor).

What's stored inside the JSON columns

Column Shape
servers.ip_addresses ["10.0.0.5", "fd00::5"]
servers.disks [{ "mount": "/", "sizeBytes": 32000000000, "usedBytes": 9000000000 }]
servers.listening_ports [{ "protocol": "tcp", "port": 22, "address": "0.0.0.0", "process": "sshd" }]
servers.last_port_scan { "at": "<ISO>", "address": "10.0.0.5", "from": 1, "to": 1024, "open": 3, "refused": 1010, "filtered": 11, "responded": true }
servers.tags ["prod", "media"]
audit_log.detail Free-form per action — e.g. { "name": "pve1" }, or for settings { "sections": [...], "changes": { "<section>": { "<field>": { "from": …, "to": … } } } }. For the notification channels (Gotify, ntfy, SMTP, webhook) only the field names that changed are recorded, never values.
integrations.config The non-secret fields for that integration type (table below).
dns_providers.config Non-secret provider settings (base URL, zone list, …).

integrations.config by type (the secret fields go to integration_credentials instead):

Type In config Encrypted separately
proxmox url, tokenId, insecure tokenSecret
pbs url, tokenId, insecure tokenSecret
synology url, username, insecure password
semaphore, gitea, dockhand url token
tailscale tailnet apiKey
uptimekuma url, username, loginUsername, syncMaintenance password (an API key, or the password on old installs), loginPassword
phpipam url, appId, insecure token
osticket host, port, database, username, tablePrefix, apiUrl, apiInsecure password, apiKey
unifi url, username, site, selfHosted, insecure apiKey (or password, with username)
npm (Nginx Proxy Manager) url, email, insecure password
homeassistant url, insecure token

Settings keys

Each section is one row in settings, with a JSON object as its value. Fields that were never changed aren't stored; the app fills in defaults when reading.

Key Holds
gotify, ntfy, smtp, webhook The four notification channels: enabled, address, and credentials (token / password / secret). The credential fields are stored encrypted (prefix enc:v1:) — see Retention and backups.
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 Settings → Notifications → Alert tickets. The API address and key are on the osTicket integration, not here.
nameGenerator themes — the Generator's server-name lists: [{ "id", "label", "names": [...], "lastImport"? }]. Edited under Settings → Names.

Rows whose key starts with _internal: are scheduler bookkeeping, not settings, and aren't part of the app's settings object:

Key Value
_internal:secretCheckLastRunDate, tailscaleKeyCheckLastRunDate, dockerUpdateCheckLastRunDate, proxmoxBackupCheckLastRunDate, pbsVerificationCheckLastRunDate The date a daily check last ran, so a restart doesn't repeat it (or skip it).
_internal:logRetentionLastRunAt When the log purge last ran.
_internal:integration_history_since When the app first began writing integrations' failing / working-again moments; the uptime ribbons claim nothing earlier for integrations.
_internal:alertTicketsBaselineDone, _internal:alertTicketsLastRun Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result.
_internal:webPushVapid JSON {publicKey, privateKey}: the server's own key pair for web push, made the first time it is needed. The private half is encrypted like the other credentials. Replacing it (deleting the row) makes every browser subscribe again.
_internal:healthActiveConditions, _internal:automationActiveConditions, _internal:endpointActiveConditions JSON: the problems currently active (health checks; automation runs; endpoint checks and heartbeats), so each is announced once and again when it clears, and survives a restart.
_internal:flapState JSON, by alert key: the recent raises of each alert and whether it is flapping (see NOTIFICATIONS.md), so a restart remembers what is being held.
_internal:unifiSync, _internal:homeAssistantSync JSON, by integration id: how the last read of each controller or Home Assistant went (at is the last successful read; one older than twenty minutes is not judged).
_internal:selfBackupLastAttempt JSON: how the last attempt to back this database up went (time, whether it worked, why not).
_internal:endpointSuggestionsDismissed, _internal:dependencySuggestionsDismissed JSON arrays of the suggestion keys somebody said "not that" to.
_internal:metricsRollupBackfilled, _internal:endpointHourlyBackfilled The time the hourly and daily summaries were first built from the samples already kept (once, after they were added).

What happens on delete

Deleting… Effect
a server Its scheduled_tasks, server_links, server_ports, server_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, by target_type)
  • maintenance_aliases.target_id (the same, by target_type)
  • endpoint_checks.server_id and heartbeats.server_id (→ a server), and patch_plans.integration_id, .tags and .server_ids (→ a Semaphore integration, server tags, servers) and restore_tests.subject_key (→ a Proxmox guest, by integration and vmid)
  • dependencies.from_id and to_id (→ a server or integration, by their _type)
  • audit_log.target_id
  • dns_records_cache.zone_id (→ dns_zones_cache.zone_id, same provider)
  • servers.tags (→ tag_definitions.name)
  • consistency_ignores.key
  • notes.target_id and todos.target_id (→ a server or a network device, by target_type) and runbooks.target_id
  • alert_rules.server_id (→ a server; a rule for a server that is gone judges nothing)
  • alert_acks.alert_key, alert_snoozes.alert_id, alert_tickets.alert_key and alert_incidents.alert_key (→ an alert, by its id on the Alerts page: the same problem has the same id)
  • network_devices ↔ dependencies and maintenance_windows with device as their type (→ network_devices.id)

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 and ntfy tokens, the SMTP password and the webhook secret — are in the settings rows, and are encrypted in place with the same key: each is stored as enc:v1: followed by the same iv:authTag:ciphertext form, and the rest of the row (URLs, topics, priorities) stays readable. The app decrypts them when settings are read and encrypts them when they're written, so nothing else sees the difference.

  • A value saved by an older version (plain text) still works, and is encrypted the next time the server starts.
  • Without CREDENTIALS_ENCRYPTION_KEY, new notification credentials can only be stored as plain text, and the server warns about it at startup. They are encrypted at the next start once the key is set.
  • If the key is changed or lost, the stored credentials can't be read: they show as empty, and the server logs which ones. Enter them again under Settings → Notifications. Editing a different field of the same channel meanwhile doesn't overwrite the old ciphertext, so putting the right key back restores them.

Everything else in the file — IP addresses, hostnames, secret names and expiry dates, the audit log — is readable by anyone who can read the file, so treat the file and its backups as sensitive anyway.

Backups.

  • Settings → Data → Backup exports the settings, the integrations and the DNS providers (with their credentials decrypted, then wrapped in a file encrypted with a passphrase you choose). Importing merges the settings over the current ones, and adds integrations and providers that don't exist yet (matched by type and name) — it never overwrites an existing integration. It does not include servers, tasks, secrets, IP addresses, domains, ports, tags, maintenance windows or logs.
  • A full backup is a copy of the SQLite file, together with the value of CREDENTIALS_ENCRYPTION_KEY — without that key the stored integration credentials can't be decrypted. Copy the file while the app is stopped, or take a snapshot while it runs, so you don't capture it mid-write. BACKUP.md has the commands (the container has no sqlite3 tool), a nightly script, and how to restore.

Changing the schema

  1. Edit server/src/db/schema.ts.
  2. From the repo root run npm run db:generate; it writes a new numbered SQL file to server/drizzle/ (and updates server/drizzle/meta/).
  3. Read the generated SQL. SQLite can add a column but can't change or drop a foreign key, so some changes become a table rebuild — which is also why the Proxmox link described above is the way it is.
  4. Start the server (or run npm run db:migrate); the migration is applied and recorded in __drizzle_migrations.
  5. Commit the schema, the SQL file and the meta/ changes together, and update this document.