Files
Homelab-manager/DATABASE.md
T
bobbanandClaude Sonnet 5.5 be6c5552bd Patch plans, a monthly report and new-port alerts
Patch plans (Updates -> Patch plans): updates on a schedule, one server at a time, each by an
ordinary update run, stopping at the first failure by default, silencing what depends on a
server while it is updated, with one message at the end.

Monthly report (Operations -> Monthly report, and optionally a message on a day of the month):
availability, incidents, updates, restore tests, backups and renewals for a calendar month,
printable. Backed by daily endpoint figures and a record of renewals.

New ports: the first report with ports is the baseline; a TCP port that begins listening later and
is not noted on the server's Ports card is a warning, cleared by Mark as expected.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-19 23:16:14 +02:00

59 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 … 0033), applied automatically when the server starts. Which ones have run is recorded in the table __drizzle_migrations.
Tables 35 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, the only indexes are the unique ones listed per table. There are no secondary indexes; the data sets here (hundreds to a few thousand rows) don't need them.

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)"
    integration_credentials ||--o{ dns_providers : "credential (set null)"
    dns_providers ||--o{ dns_zones_cache : "cascade"
    dns_providers ||--o{ dns_records_cache : "cascade"
    servers ||--o{ scheduled_tasks : "cascade"
    servers ||--o{ server_links : "cascade"
    servers ||--o{ server_metrics : "cascade"
    servers ||--o{ server_ports : "cascade"
    servers ||--o{ port_forwards : "optional (set null)"
    integrations ||--o{ servers : "proxmox link (app clears it)"
    integrations ||--o{ alert_tickets : "osTicket used (set null)"

Seventeen tables stand alone, with no foreign keys: settings, secrets, ipam_entries, domains, diag_log, notification_queue, consistency_ignores, tag_definitions, share_links, maintenance_schedules, metrics_tokens, event_webhooks, alert_incidents, dependencies, endpoint_checks, restore_tests, heartbeats. maintenance_windows and maintenance_aliases also have no foreign key — see soft references.

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.
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, 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, alert (ack, unack — with the alert's id; on the thing it is about, so they show on a server's Activity card), incident (note, note_removed), db_backup (create, upload, download, delete, restore_staged, restore_cancelled, settings), 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.
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
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.
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 Infrastructure → 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.

Index server_metrics_lookup_idx on (server_id, metric, recorded_at).

server_ports

A port on one server that's been seen open by a scan, or that someone wrote a note about. Rows exist only while they carry information. What the agent sees is stored on the server row instead (servers.listening_ports).

Column Type Notes
id integer PK
server_id integer NOT NULL → servers.id, cascade
port integer NOT NULL
protocol text NOT NULL, default tcp tcp | udp.
label, comment text
open bool NOT NULL, default 0 True when the last scan connected to it.
last_seen_open_at text
updated_at text NOT NULL

Unique index server_ports_unique on (server_id, port, protocol).

port_forwards

Manually recorded port openings on something this app doesn't monitor — a router's port forward, an edge firewall rule, a cloud security group. It records them; it can't check or change them.

Column Type Notes
id integer PK
label text NOT NULL
external_port integer NOT NULL
protocol text NOT NULL, default tcp tcp | udp.
server_id integer → servers.id, set null Optional: the tracked server it points at.
destination text Anything else — a bare IP, an untracked device — or detail alongside server_id.
internal_port integer When NAT changes the port.
source text Free text: where the rule lives ("Home router", "OPNsense WAN rule").
comment text
created_at, updated_at text NOT NULL

Integrations and credentials

integrations

A connected system: Proxmox, Synology, Semaphore, Tailscale, Gitea, Dockhand, Uptime Kuma, phpIPAM, Proxmox Backup Server, osTicket.

Column Type Notes
id integer PK
type text NOT NULL proxmox | synology | semaphore | tailscale | gitea | dockhand | uptimekuma | phpipam | pbs | osticket.
name text NOT NULL
base_url text NOT NULL For osTicket (a direct database connection) this holds the database host.
credential_id integer → integration_credentials.id, set null
config text JSON of the non-secret settings, see below.
enabled bool NOT NULL, default 1
created_at text NOT NULL

integration_credentials

The secret half of an integration or DNS provider, encrypted at rest.

Column Type Notes
id integer PK
name text NOT NULL "<type>:<name>", for recognising a row when looking at the file.
encrypted_secret text NOT NULL iv:authTag:ciphertext, each in hex — AES-256-GCM with CREDENTIALS_ENCRYPTION_KEY. The plaintext is a JSON object of the secret fields (an API token, a password). Without the same key it can't be read.
created_at text NOT NULL

The notification channels' credentials aren't in this table; they're encrypted in place in settings — see Retention and backups.

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

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.

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.

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 From that report.
poll_errors integer 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.

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 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.

Column Type Notes
id integer PK
from_type, from_id text, integer NOT NULL The thing that needs: server or integration, and its id.
to_type, to_id text, integer NOT NULL The thing it needs. Unique together with the pair above.
created_at text NOT NULL ISO.

No foreign keys (like maintenance_windows): a row whose server or integration is gone is ignored, not an error.

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.
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

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).

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 password (an API key, or the password on old installs)
phpipam url, appId, insecure token
osticket host, port, database, username, tablePrefix password

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.
signIn Roles from groups: roleFromGroups (false), groupsClaim (groups), adminGroups, operatorGroups, otherwise (viewer or keep).
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.
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). A server can override each of these (see servers.thresholds).
logRetention enabled, retentionDays (90), intervalHours (24).
display dateFormat, timeFormat, pageSize.
providerColors, integrationColors Badge colours, by provider / integration type.
consistency excludedRanges — addresses the Consistency and IP Addresses pages ignore. Default ["172.16.0.0/12"] (Docker's networks).
alertTickets Opening osTicket tickets for alerts: enabled, integrationId, severities, categories, requesterName/requesterEmail, topicId, priorityId, notifyStaff, existingProblems, confirmChecks, summaryAbove, reopenAfterMinutes. Edited under Settings → Notifications → Alert tickets. The API address and key are on the osTicket integration, not here.
nameGenerator themes — the Generator's server-name lists: [{ "id", "label", "names": [...], "lastImport"? }]. Edited under Settings → Names.

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

Key Value
_internal:secretCheckLastRunDate, tailscaleKeyCheckLastRunDate, dockerUpdateCheckLastRunDate, proxmoxBackupCheckLastRunDate, pbsVerificationCheckLastRunDate The date a daily check last ran, so a restart doesn't repeat it (or skip it).
_internal:logRetentionLastRunAt When the log purge last ran.
_internal:integration_history_since When the app first began writing integrations' failing / working-again moments; the uptime ribbons claim nothing earlier for integrations.
_internal:alertTicketsBaselineDone, _internal:alertTicketsLastRun Whether the alert-ticket starting line has been recorded since the feature was switched on, and JSON for the last check's result.
_internal:webPushVapid JSON {publicKey, privateKey}: the server's own key pair for web push, made the first time it is needed. The private half is encrypted like the other credentials. Replacing it (deleting the row) makes every browser subscribe again.
_internal:healthActiveConditions, _internal:automationActiveConditions JSON: the problems currently active, so each is announced once and again when it clears, and survives a restart.

What happens on delete

Deleting… Effect
a server Its scheduled_tasks, server_links and server_ports are deleted with it. Port forwards that pointed at it stay, with server_id cleared.
a DNS provider Its cached zones and records are deleted.
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.
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

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. Only the two logs are trimmed: audit_log and diag_log entries older than logRetention.retentionDays are deleted by the purge job (off by default), and notification_queue is emptied each time the quiet-hours digest is sent. 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.