Files
Homelab-manager/DATABASE.md
T
bobbanandClaude Sonnet 5.5 906220040e Add a since-you-last-looked summary, 30-day uptime ribbons, a maintenance timeline and hover timestamps
- Dashboard card on what changed since the user pressed Got it (users.last_looked_at,
  migration 0021), folding each problem and its recovery into one line.
- Uptime ribbons on servers and integrations, built from the audit log; integrations'
  failing/working-again moments are now recorded.
- Timeline of running and scheduled maintenance windows on the Maintenance page.
- TimeAgo component: relative times with the exact time in the chosen format on hover.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-16 21:55:04 +02:00

616 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Database schema
Homelab Manager keeps its data in one SQLite file, accessed through
[drizzle-orm](https://orm.drizzle.team) and the libSQL client. The schema is
defined in one place — [`server/src/db/schema.ts`](server/src/db/schema.ts) —
and this document describes it. It was checked against a fresh database built
from the migrations, so the tables, columns, foreign keys and indexes below are
what the app actually creates.
- [The basics](#the-basics)
- [How the tables relate](#how-the-tables-relate)
- [Tables](#tables)
- [What's stored inside the JSON columns](#whats-stored-inside-the-json-columns)
- [Settings keys](#settings-keys)
- [What happens on delete](#what-happens-on-delete)
- [The Proxmox link's foreign key](#the-proxmox-links-foreign-key)
- [Retention and backups](#retention-and-backups)
- [Changing the schema](#changing-the-schema)
## The basics
| | |
|---|---|
| **File** | `DATABASE_PATH`, default `../data/homelab-manager.sqlite` (relative to `server/`; `/app/data/...` in Docker). The folder is created if missing. |
| **Foreign keys** | Switched on for every connection (`PRAGMA foreign_keys = ON`), so the `ON DELETE` rules below are enforced. |
| **Migrations** | SQL files in [`server/drizzle/`](server/drizzle) (`0000` … `0014`), applied automatically when the server starts. Which ones have run is recorded in the table `__drizzle_migrations`. |
| **Tables** | 24 application tables, plus drizzle's own `__drizzle_migrations`. |
**Not in the database:**
- **Login sessions** are files in `SESSION_DIR` (default `../data/sessions`), not rows.
- **The encryption key** for integration credentials (`CREDENTIALS_ENCRYPTION_KEY`) and the session secret live in the environment, never in the file.
- **Agent tokens** are never stored: only a SHA-256 hash and a short prefix of each (`servers.api_token_hash`, `api_token_prefix`). The token itself is shown once, when the server is registered.
### Conventions
- **Primary keys** are `INTEGER PRIMARY KEY AUTOINCREMENT` named `id` — except `settings`, which uses its text `key`.
- **Booleans** are `INTEGER` 0/1 (shown as `bool` below).
- **Timestamps are text, in two formats**, so read them with care:
- Columns the database fills in itself (`created_at`, and most `updated_at`) use SQLite's `current_timestamp`: `2026-10-03 14:05:09`, **UTC, with no zone marker**. Treat it as UTC, not local time.
- Columns the app fills in (`last_seen_at`, `last_login_at`, `synced_at`, `last_checked_at`, …) use ISO 8601: `2026-10-03T14:05:09.123Z`.
- Dates without a time (`secrets.expiry_date`, `domains.expires_at`) are `YYYY-MM-DD`.
- **JSON columns** are `TEXT` holding JSON; see [what's inside](#whats-stored-inside-the-json-columns).
- **Enumerations** (roles, types) are plain text — SQLite doesn't enforce the allowed values; the app does.
- **Indexes:** besides primary keys, 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
```mermaid
erDiagram
users ||--o{ audit_log : "actor (set null)"
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)"
```
Eight tables stand alone, with no foreign keys: `settings`, `secrets`,
`ipam_entries`, `domains`, `diag_log`, `notification_queue`,
`consistency_ignores`, `tag_definitions`. `maintenance_windows` and `maintenance_aliases` also have no
foreign key — see [soft references](#soft-references-not-foreign-keys).
## 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. Follows them to any browser. |
| `last_looked_at` | text | ISO time this person last pressed "Got it" on the dashboard's "Since you last looked" card; the next summary starts there (null = never: the last day is shown). |
#### `audit_log`
Who changed what. Written by the app on every change (see
[ROLES.md](ROLES.md) for who can read it).
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `actor_user_id` | integer → `users.id`, **set null** on delete | Null for automatic actions, and for entries whose user was deleted. |
| `actor_label` | text | The user's name/email as it was at the time (or `system`), so an entry still reads correctly after the account is gone. |
| `category` | text NOT NULL | Free text. In use: `server` (including the health check's own `went_offline`, `back_online`, `disk_full` and `disk_ok`, 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`, `ipam`, `secret`, `domain`, `tag`, `task`, `session`, `network`, `maintenance`, `consistency`, `user`, `privacy`, `diag_log`, `alert_ticket`. |
| `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 | |
| `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; 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_aliases`
An address that Uptime Kuma's monitors use for something this app knows by another address, so the Uptime Kuma
maintenance sync can find it. Added on the Maintenance page.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `address` | text NOT NULL | A bare lowercase host: a name or an IP. |
| `target_type` | text NOT NULL | `server` | `integration` | `dns_provider`. |
| `target_id` | integer NOT NULL | The ID in the table `target_type` names. **Not a foreign key**; an alias whose target was deleted is ignored. |
| `created_at` | text NOT NULL | |
Unique on (`address`, `target_type`, `target_id`).
### Servers
#### `servers`
A machine that reports in through the agent (or is registered by hand), plus
what it last reported.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | Not unique. |
| `hostname` | text | |
| `os_type` | text NOT NULL, default `linux` | |
| `description` | text | |
| `api_token_hash` | text NOT NULL | SHA-256 of the agent's token. |
| `api_token_prefix` | text NOT NULL | First characters of the token, to tell tokens apart in the UI. |
| `created_at` | text NOT NULL | SQLite UTC. |
| `last_seen_at` | text | ISO; when the agent last reported. Drives "server offline". |
| `ip_addresses` | text | JSON `string[]`. Agent-reported. |
| `cpu_model` | text | Agent-reported. |
| `cpu_cores` | integer | |
| `cpu_load_percent` | real | Load average ÷ cores × 100 — an approximation, not instantaneous usage. |
| `mem_total_bytes`, `mem_used_bytes` | integer | |
| `disks` | text | JSON, see below. Agent-reported. |
| `listening_ports` | text | JSON, see below. What the agent sees bound on the host. |
| `last_port_scan` | text | JSON summary of the latest network scan *from this app*. |
| `tags` | text | JSON `string[]` of normalised tag names. |
| `proxmox_integration_id` | integer → `integrations.id` | The database has no `ON DELETE` rule here; the app clears the link itself — see [below](#the-proxmox-links-foreign-key). |
| `proxmox_node` | text | |
| `proxmox_guest_type` | text | `qemu` \| `lxc`. |
| `proxmox_vmid` | integer | The four `proxmox_*` columns are set together or cleared together (enforced by the API), by an admin — never by the agent. |
| `hide_proxmox_link` | bool NOT NULL, default 0 | Hides the "Proxmox link" card for servers that aren't Proxmox guests. Ignored while the server is actually linked. |
#### `scheduled_tasks`
Cron jobs, systemd timers and Windows tasks the agent found on a server, plus
tasks added by hand.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `server_id` | integer NOT NULL → `servers.id`, **cascade** | |
| `schedule_type` | text NOT NULL | `cron` \| `systemd_timer` \| `windows_task` from agents; manual tasks may use others (`docker`, `backup`, `update`, `n8n_workflow`, `manual`). |
| `origin` | text NOT NULL, default `agent` | `agent` \| `manual`. Manual rows are never touched by agent sync. |
| `name` | text NOT NULL | |
| `command`, `schedule_expression`, `source` | text | |
| `enabled` | bool NOT NULL, default 1 | |
| `next_run_at` | text | |
| `raw_metadata` | text | JSON as the agent reported it. |
| `is_stale` | bool NOT NULL, default 0 | Set when the agent stops reporting the task. |
| `first_seen_at`, `last_seen_at` | text NOT NULL | SQLite UTC at first insert; later updates are written by the app. |
#### `server_links`
Admin-page bookmarks for a server (Dockge, Webmin, Cockpit, …). Shown on the
server's page and summarised under Operations → 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](#retention-and-backups).
### DNS
#### `dns_providers`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_type` | text NOT NULL | `cloudflare` \| `loopia` \| `pihole` \| `azure` \| `cpanel` \| `technitium`. |
| `name` | text NOT NULL | |
| `credential_id` | integer → `integration_credentials.id`, **set null** | |
| `config` | text | JSON, non-secret provider config (base URL, zone list, …). |
| `enabled` | bool NOT NULL, default 1 | |
| `created_at` | text NOT NULL | |
#### `dns_zones_cache` and `dns_records_cache`
Local copies of what the providers returned at the last sync, so pages load
without calling every provider. The providers remain the source of truth.
`dns_zones_cache`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
| `zone_id` | text NOT NULL | The provider's own identifier for the zone. |
| `zone_name` | text NOT NULL | |
| `synced_at` | text | ISO. |
Unique index **`dns_zones_cache_provider_zone_idx`** on (`provider_id`, `zone_id`).
`dns_records_cache`
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `provider_id` | integer NOT NULL → `dns_providers.id`, **cascade** | |
| `zone_id` | text NOT NULL | The provider's zone identifier — matches `dns_zones_cache.zone_id` for the same provider, but is **not a foreign key**. |
| `record_id` | text NOT NULL | The provider's own record identifier. |
| `type` | text NOT NULL | `A`, `AAAA`, `CNAME`, `TXT`, `MX`, … |
| `name`, `content` | text NOT NULL | |
| `ttl`, `priority` | integer | |
| `proxied` | bool | Cloudflare only. |
### Address and name tracking
#### `ipam_entries`
IP addresses with a label and notes, entered by hand or synced.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `ip_address` | text NOT NULL, **unique** | |
| `label`, `vendor`, `location`, `notes` | text | |
| `source` | text | Null = typed in by hand; otherwise the sync that created it: `tailscale`, `proxmox` or `phpipam`. A sync only updates rows it created itself and never overwrites a manual one. |
| `created_at`, `updated_at` | text NOT NULL | |
#### `domains`
Registered domains whose expiry is tracked.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL, **unique** | The registrable domain, lowercase ASCII. |
| `origin` | text NOT NULL, default `manual` | `manual` (typed in) or `zone` (created from a synced DNS zone, removed again when the zone goes away). |
| `expires_at` | text | `YYYY-MM-DD`, as the registry reports it. Null for registries that don't publish one. |
| `registrar` | text | |
| `lookup_source` | text | `rdap` \| `whois`. |
| `last_checked_at` | text | Last attempt. |
| `last_checked_ok_at` | text | Last *successful* attempt. |
| `last_check_error` | text | |
| `created_at` | text NOT NULL | |
#### `secrets`
The expiry tracker for API tokens, certificates, passwords and the like. It
tracks *when* something expires; it does not store the secret itself.
| Column | Type | Notes |
|---|---|---|
| `id` | integer PK | |
| `name` | text NOT NULL | |
| `type` | text NOT NULL, default `generic` | `api_token` \| `ssl_certificate` \| `password` \| `generic`. |
| `description`, `notes` | text | |
| `expiry_date` | text | `YYYY-MM-DD`. NULL = never expires (no status, no alert). For a certificate with a host to check, overwritten from the live certificate, and never NULL. |
| `warn_days` | integer NOT NULL, default 30 | How long before expiry to start reminding. |
| `check_host`, `check_port` | text / integer | Certificates only: read the expiry from the live certificate at this host:port. |
| `last_checked_at`, `last_check_error` | text | Result of the last live check. |
| `created_at`, `updated_at` | text NOT NULL | |
### Housekeeping
#### `settings`
Key/value store for app settings. One row per settings section (the value is
JSON) plus a few internal bookkeeping rows. Details under
[Settings keys](#settings-keys).
| Column | Type | Notes |
|---|---|---|
| `key` | text PK | |
| `value` | text NOT NULL | JSON (or a plain date/time for internal flags). |
| `updated_at` | text NOT NULL | |
#### `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. |
## 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](#retention-and-backups). |
| `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`. |
| `healthChecks` | `serverOfflineMinutes` (60), `diskUsagePercent` (90), `domainWarnDays` (30), `diskForecastDays` (14; 0 = off — how far ahead a filling disk is flagged on the Alerts page). |
| `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 → 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: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`)
- `audit_log.target_id`
- `dns_records_cache.zone_id` (→ `dns_zones_cache.zone_id`, same provider)
- `servers.tags` (→ `tag_definitions.name`)
- `consistency_ignores.key`
## The Proxmox link's foreign key
`servers.proxmox_integration_id` is meant to clear itself when its integration
is deleted: `schema.ts` says `onDelete: "set null"`. The database doesn't do
that. Migration `0001` added the column as a plain
`REFERENCES integrations(id)`, and SQLite can't change a foreign key afterwards
without rebuilding the table, so the rule *in the database* is **no action**:
with foreign keys on, deleting an integration that a server points at is refused
with `FOREIGN KEY constraint failed`.
The app works around it rather than rebuilding the table. The delete route in
[`server/src/routes/integrations.ts`](server/src/routes/integrations.ts) first
clears the four `proxmox_*` columns on every server linked to that integration,
then deletes it, and the audit entry records how many servers were unlinked
(`unlinkedServers`). Deleting an integration therefore works whether or not
servers are linked to it. Anything that deletes integrations some other way —
a hand-written SQL statement, say — has to do the same first.
## Retention and backups
**Retention.** 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 → Backup** exports the settings, the integrations and the DNS
providers (with their credentials decrypted, then wrapped in a file encrypted
with a passphrase you choose). Importing merges the settings over the current ones, and adds
integrations and providers that don't exist yet (matched by type and name) — it never
overwrites an existing integration. It does **not** include servers, tasks,
secrets, IP addresses, domains, ports, tags, maintenance windows or logs.
- **A full backup** is a copy of the SQLite file, together with the value of
`CREDENTIALS_ENCRYPTION_KEY` — without that key the stored integration
credentials can't be decrypted. Copy the file while the app is stopped, or take a
snapshot while it runs, so you don't capture it mid-write. [BACKUP.md](BACKUP.md)
has the commands (the container has no `sqlite3` tool), a nightly script, and how to restore.
## Changing the schema
1. Edit [`server/src/db/schema.ts`](server/src/db/schema.ts).
2. From the repo root run `npm run db:generate`; it writes a new numbered SQL
file to `server/drizzle/` (and updates `server/drizzle/meta/`).
3. Read the generated SQL. SQLite can add a column but can't change or drop a
foreign key, so some changes become a table rebuild — which is also why the
[Proxmox link](#the-proxmox-links-foreign-key) described above is the way it is.
4. Start the server (or run `npm run db:migrate`); the migration is applied and
recorded in `__drizzle_migrations`.
5. Commit the schema, the SQL file and the `meta/` changes together, and update
this document.