CLI & Configuration

The binary has exactly one job: start a node from a config file. There are no management subcommands — databases and users are managed over SQL (see Administration).

xcon-db-server -config /etc/xcon-db/xcon-db.toml
xcon-db-server -sample-config > xcon-db.toml   # annotated starting point

Started with a -config path that does not exist, the binary serves the first-run setup wizard instead of failing — it writes this file for you and restarts into the node. Everything below is what that file holds, whether the wizard wrote it or you did.

The config file

root = "/var/lib/xcon-db-server"

[listen]
pg     = ":5432"   # pg-wire (psql, Grafana, every pg driver)
ilp    = ""        # ILP TCP ingest; empty = off
ilp_db = ""        # the database ILP lines are bound to
http   = ""        # admin console (REST + SSE + SPA); empty = off. Bind 127.0.0.1 or front with TLS.
http_dev_origin = ""  # extra CORS origin for the Vite dev server; empty = same-origin only

[tls]              # pg-wire AND (if set) the admin console; empty = plaintext
cert = ""
key  = ""

[engine]
group_commit   = "50ms"    # WAL fsync window ("0s" = fsync every write)
merge_every    = "30s"     # delta→columnar merge time trigger
merge_bytes    = 8388608   # ...and size trigger
merge_throttle = 0         # merge write budget bytes/s (0 = unlimited)
statement_timeout = "0s"   # wall-clock cancel for ONE statement ("0s" = off); e.g. "600s" as a runaway-scan backstop

The config never holds credentials — there is no [admin] section, and the server refuses to start if it finds one (a leftover from older versions). Admins live in the user store inside root, password-hashed; the file itself is safe to read. When installed from apt it lives at /etc/xcon-db/xcon-db.toml and the wizard writes it.

The admin console is the web UI at the http address: the same SPA the setup wizard runs in, signed into with an admin account from the user store. Leave http = "" to run headless (pg-wire only).

A fresh data root has no admin. The node still starts and serves data — it just logs how to get in:

xcon-db: no admin exists — create one with: xcon-db-server -config <file> -reset-admin <user>

-reset-admin <user> is an offline verb (stop the server first): it creates the admin if absent or resets an existing one's password, then exits. The new password is read from stdin, never argv — type it (it echoes) or pipe it to hide:

printf '%s' "$NEWPASS" | xcon-db-server -config /etc/xcon-db/xcon-db.toml -reset-admin xcon

The setup wizard creates the first admin the same way. Every admin — including the first — can be altered or dropped over SQL like any other; there is no permanent, un-droppable bootstrap user.

Administration over SQL

Connect as the admin (any client; with psql: psql "postgres://xcon:...@host:5432/xcon" — the database name is ignored for admins) and manage the node:

Statement	Meaning
SHOW DATABASES	Every database (admins); a database user sees its own
CREATE DATABASE acme	New empty database (names: [a-z0-9][a-z0-9_-]{0,63}); needs the CREATEDB switch
DROP DATABASE acme	Delete the database and its data; needs the DROPDB switch
SHOW USERS	List users (user, database, admin, owner, active, createdb, dropdb)
CREATE USER u PASSWORD 'p' DATABASE acme [OWNER]	New user bound to exactly one database; OWNER lets it manage that database's users
CREATE USER u PASSWORD 'p' ADMIN [CREATEDB] [DROPDB]	Another node admin, with its safety switches
ALTER USER u PASSWORD 'p'	Reset a password
ALTER USER u ENABLE|DISABLE	A disabled account keeps its data and settings but cannot log in
ALTER USER u CREATEDB|NOCREATEDB|DROPDB|NODROPDB	Flip an admin's safety switches
DROP USER u	Remove a user

Database and admin management is admin-only; CREATEDB/DROPDB are an admin's safety switches over database lifecycle — accident guards, not a privilege hierarchy (any admin can flip another admin's switch; the config-file admin holds both, always). User management is also delegated to owners: connected to its own database, an owner runs CREATE USER u PASSWORD 'p' [OWNER] (the database is implicit), ALTER USER (password, enable/disable), DROP USER and SHOW USERS, all scoped to that database. Any user may change its own password. Nobody drops or disables themselves, and the config-file admin is out of SQL's reach entirely. The admin session is management-only in return — data statements need a database user. Passwords are stored as SCRAM-SHA-256 verifiers, never in cleartext.