Configuration

NYXDB's primary runtime configuration is the nyxdb command line. Storage topology can be imported from YAML, after which catalog DDL is authoritative. Always derive defaults from nyxdb --help in the exact artifact being deployed.

Baseline

nyxdb \
  --host=127.0.0.1 \
  --port=7510 \
  --data-dir=/srv/nyxdb/data \
  --require-auth \
  --admin-password-file=/run/secrets/nyxdb-admin-password \
  --wal-sync=always \
  --memory-limit-bytes=15032385536 \
  --memory-governor=on

Choose values from workload and recovery tests; the example is not a universal sizing prescription.

Configuration groups

Group	Representative controls	Review question
Listener	`--host`, `--port`, connection count/workers, handshake/idle/frame/write timeouts	Can a client consume an unbounded worker or socket?
Access	`--require-auth`, first-boot admin secret, operator users/grants, application auth providers/endpoints/limits	Can any reachable socket skip authentication or cross identity planes?
Persistence	`--data-dir`, `--wal-sync`, `--journal-commit`	What does an acknowledged write survive?
Storage I/O	`--storage-io`, depth, mmap, flush thresholds/polling	Is the selected backend proven on this kernel/filesystem?
PSI	delivery mode, lane workers, ring capacity, source partitions	Can stream fan-out and lag remain bounded?
Committed tail	row/byte caps, delay ramp, seal, publisher threads, spill	What happens when ingest outruns flush?
Memory	process limit, governor, sealed-memory cap, spill, allocator release	Does pressure degrade to bounded latency/rejection before OOM?
Compaction/cache	polling, job/I/O limits, cache profile and byte caps	Is background work isolated from foreground reads?
Ingest	profile, queue count/bytes, workers, coalescing	Is parked decoded input bounded in bytes?
Query	concurrency, queue, timeout, row/output/operator/cardinality limits	Can one query monopolize the process?
Telemetry	system tick and query-log retention	Is incident data useful and bounded?

Use the full help output for exact flag names, ranges, and revision-specific defaults.

Defaults worth making explicit

Control	Current executable default
Live connections	256
Connection workers	256
Handshake timeout	10 s
Idle timeout	300 s
Frame timeout	30 s absolute
Write timeout	30 s absolute
Operator authentication enforcement	Off; without `--require-auth`, every connection is an implicit full-SQL operator
Native TLS and Origin policy	Absent; the server exposes raw TCP and `ws://` and must remain behind a reviewed trusted-network edge
WAL sync	`group`
PSI delivery	`async`
PSI ring capacity	65,536 per exact source
Committed-tail rows	10,000,000
Committed-tail bytes	2 GiB
Memory governor	on
Memory ramp / block	80% / 95%, with 2% downgrade hysteresis
System snapshot tick	1,000 ms; inputs below 100 ms clamp to 100 ms

Explicit values make a future default change visible in code review.

Access posture

--require-auth is mandatory for every browser-facing or otherwise untrusted listener. Auth providers protect the end-user endpoint path; they do not close the default-open operator path. The native listener has no TLS, so place it on a trusted network behind reviewed TLS termination plus Origin and network policy before an untrusted client can reach it.

On a fresh catalog with no users, NYXDB seeds admin with role admin. Supply the first-boot password through a mounted secret file:

nyxdb \
  --data-dir=/srv/nyxdb/data \
  --require-auth \
  --admin-password-file=/run/secrets/nyxdb-admin-password

Secret-source precedence is:

--admin-password-file=<path>;
NYXDB_ADMIN_PASSWORD_FILE;
--admin-password=<password>; and
NYXDB_ADMIN_PASSWORD.

File inputs strip trailing newlines and fail startup when explicitly selected but unreadable or empty. The inline flag and environment variable are supported for provisioning but can leak through process inspection or orchestration metadata. If no source is supplied, the engine generates a random 24-character password and prints it once. With --data-dir, the user catalog persists and the resolved value no longer changes the existing admin after seeding. However, an explicitly configured password file is still opened and validated on every process start. Keep it mounted and readable, or remove the file flag/environment source from the reviewed startup command after provisioning. Without persistence, seeding runs again on every start.

--require-auth allows one capability negotiation, ping, and either operator or end-user OP_AUTH before authentication; it gates other operations. It does not configure application users. Direct application access separately requires an auth provider, a typed endpoint or granted logical view, and the appropriate limits. See Operator governance and Application access SQL.

Operator grants gate raw query/stream operations and the canonical stored query behind operator-class endpoint/view execute or subscribe operations. Named non-admin operators need read or subscribe on every scanned base relation; operator-class calls remain exempt from application endpoint quotas.

Storage YAML ownership

--storage-config=<file> imports resources, pools, and policies that do not already exist in the catalog. Once an object exists:

the catalog definition wins;
YAML drift produces a warning; and
operators use CREATE, ALTER, or DROP storage DDL for changes.

Invalid YAML or invalid imported topology is fatal at boot. Do not edit the file expecting an existing catalog object to change silently.

Change procedure

Capture the old command line, help output, artifact identity, and baseline telemetry.
Change one resource policy at a time.
Validate the candidate with representative ingest, read, stream, restart, and memory-pressure workloads.
Schedule a clean offline restart.
Verify the effective build and startup log.
Compare query, event, memory, part, and subscription telemetry.
Keep the previous configuration with the pre-change backup evidence.

Removed compatibility flags may still parse and warn while doing nothing. Treat startup warnings as review failures, not harmless noise.