Files
Homelab-manager/DATABASE.md
T
bobbanandClaude Sonnet 5.5 44e393f172 Add saved filter views, a customisable dashboard, server comparison, row keyboard navigation and share links
- Table search, status, tag and sort live in the address; Save view pins one as a favourite.
- Dashboard cards can be moved and hidden per user (users.dashboard_layout, migration 0022).
- Compare two to four servers' load, memory or disk on one chart.
- j/k move through table rows that open a detail panel.
- Share links open a read-only wall without signing in, numbers only or with names
  (share_links, migration 0023); the wall is split into a shared view over two data sources.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-16 22:15:29 +02:00

34 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 … 0023), applied automatically when the server starts. Which ones have run is recorded in the table __drizzle_migrations.
Tables 25 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.
  • 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)"
    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)"

Nine tables stand alone, with no foreign keys: settings, secrets, ipam_entries, domains, diag_log, notification_queue, consistency_ignores, tag_definitions, share_links. 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.
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.
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, 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, share_link (a link made or removed — never the secret).
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
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.
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.

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.

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.

Addresses that open a read-only wall display without signing in (Settings → Share links). 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 summary (numbers only) or names (also the names of what is wrong, in maintenance, and the integrations).
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.

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

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