Documentation / Configuration

Configuration

Every setting is a command-line flag on nusadb-server. Defaults are chosen to stay healthy on a small host; a larger machine raises them deliberately.

Server flags

Flag	Default	Purpose
`--listen`	`0.0.0.0:5678`	TCP address for the wire protocol.
`--data-dir`	`./data`	Data directory; holds the write-ahead log, which is the durable copy of the data.
`--auth-user USER:PASSWORD`	none	Require SCRAM-SHA-256 for this user. Repeatable. Once any is set, every connection must authenticate.
`NUSADB_USER` + `NUSADB_PASSWORD`	none	Environment fallback when no `--auth-user` is given. Setting only one is an error.
`--tls-cert` / `--tls-key`	none	PEM chain and key; TLS is enabled when both are set.
`--tls-client-ca`	none	PEM CA for mutual TLS: every client must present a certificate signed by it.
`--metrics-listen`	off	Serve Prometheus metrics on this address, for example `127.0.0.1:9100`.
`--max-connections`	`25`	Cap on concurrent connections; excess queue. `0` is unlimited.
`--idle-timeout`	`0`	Close a connection idle this many seconds. `0` is no limit.
`--statement-timeout`	`0`	Cancel statements running longer than this many seconds.
`--drain-timeout`	`30`	On shutdown, wait this long for in-flight connections to finish.
`--mem-budget`	`0`	Engine memory budget in bytes; new transactions are refused past it instead of the process being killed by the system.
`--max-resident-bytes`	derived	Ceiling on each database's in-memory page store. Row inserts past it are refused with an error naming the limit.
`--work-mem`	`0`	Per-query materialisation budget in bytes; a query over it fails with a clear error rather than exhausting memory.

RUST_LOG sets log verbosity, for example RUST_LOG=info.

Production checklist

Require authentication with at least one --auth-user or the environment pair; terminate TLS with --tls-cert and --tls-key; and keep --data-dir on a persistent volume you back up. With no credentials the server runs trust-on-startup: every client is accepted and no password is asked for. It logs a warning at start-up.

Resource defaults

NusaDB defaults small and scales up explicitly. A fresh install is tuned to stay healthy on a host with about 2 GB of RAM and one or two cores, with no flags set, rather than defaulting to values that exhaust a small machine. A larger host raises the limits on purpose.

Resource	Default	Raise it with
Concurrent connections	25	`--max-connections`, or an external pooler
Engine memory budget	unlimited	`--mem-budget` on a constrained host
Per-query work memory	unlimited	`--work-mem`
Version-store purge workers	1	sufficient at this scale

The memory budget ships off because its safe value depends on measured resident size on the host in question, and a guessed number would be worse than none. Set --mem-budget explicitly to cap memory today. A declarative profile file that sets these together is planned.

Running as a service

ini

[Unit]
Description=NusaDB
After=network-online.target

[Service]
User=nusadb
Group=nusadb
ExecStart=/usr/local/bin/nusadb-server \
  --listen 0.0.0.0:5678 \
  --data-dir /var/lib/nusadb \
  --auth-user app:CHANGE_ME \
  --tls-cert /etc/nusadb/server.crt \
  --tls-key /etc/nusadb/server.key \
  --metrics-listen 127.0.0.1:9100 \
  --max-connections 100
Restart=on-failure
Environment=RUST_LOG=info

# The server only needs its own data directory writable.
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
NoNewPrivileges=true
ReadWritePaths=/var/lib/nusadb

[Install]
WantedBy=multi-user.target

Put the credential in a unit drop-in or an environment file readable only by root rather than in a world-readable unit, and keep the metrics port on localhost, because it is not authenticated.

Metrics

With --metrics-listen set, the server answers Prometheus scrapes in the text exposition format.

Metric	Type	Meaning
`nusadb_connections_total`	counter	Connections accepted since start.
`nusadb_connections_active`	gauge	Connections currently open.
`nusadb_queries_total`	counter	Statements executed.
`nusadb_query_errors_total`	counter	Statements that returned an error.

That is enough to see whether the server is up and busy, and not enough for latency analysis: there are no query-duration histograms, per-database counters, or write-ahead log and storage metrics yet. Given the retry behaviour described under transactions, a serialization-conflict counter is a gap worth knowing about. Track conflicts from the application side for now.

Upgrades and engine changes

Each database directory records which storage engine wrote it. A directory written by the removed lsm engine is refused at start-up rather than misread; migrating means exporting from the last release that shipped that engine and reloading into a fresh data directory. Read the release notes before upgrading a data directory in place.

PreviousClients and protocol NextLimits and capacity