Getting started

@rivyn/db-server is a self-hosted NoSQL database with a MongoDB-like document model. No cloud, no accounts — you run it on your own machine or VPS and connect to it with @rivyn/db.

Install and run

npm i -g @rivyn/db-server
rivyn-server init     # creates rivyn.config.json and prints your auth key
rivyn-server start

The server listens on tcp://0.0.0.0:7223 by default. Keep the auth key safe — clients cannot connect without it.

Rivyn Studio

A web UI ships with the server and starts alongside it at http://127.0.0.1:7224. Log in with your auth key to browse collections, run filter queries, edit documents and manage indexes.

Studio binds to localhost by default. To reach a remote server's Studio, tunnel to it rather than exposing the port:

ssh -L 7224:127.0.0.1:7224 user@your-server

Indexes

Indexes take a field name or a dotted path. A path that crosses an array builds a multikey index — the document is indexed under every value the path yields, and still comes back once:

await users.createIndex("level.xp");           // range queries
await users.createIndex("punishments.active"); // multikey
await users.createIndex("id", { unique: true });

The planner uses an index only when the filter names exactly that field. Everything else is a full scan — in memory, so fast, but linear in collection size.

Rate limiting

maxOpsPerSecond defaults to 2000 per IP. A busy application will reach that and start receiving rate limit exceeded errors, which surface as failed queries rather than slow ones. Raise it in rivyn.config.json before putting the server under real load:

{ "maxOpsPerSecond": 50000 }

Storage

Each collection lives in data/<name>/:

• journal.log — append-only operation log, one CRC32-prefixed JSON entry per line
• snapshot.riv — JSONL snapshot, written atomically
• meta.json — index definitions and any server-side schema

Writes append to the journal. Once it reaches 1000 entries a snapshot is written in the background and the journal is rotated. On startup the server loads the snapshot and replays the journal; a torn tail from a power loss is detected by CRC and truncated safely.

Durability

Choose how aggressively writes reach the disk:

Backups

rivyn-server backup ./backups/2026-07-19

Backup works while the server is running: it detects the data directory lock, asks the live server to flush its snapshots over the wire, then copies the directory. Restore still requires the server to be stopped:

rivyn-server restore ./backups/2026-07-19 --force

Security

Key authentication is mandatory and compared in constant time. On top of that the server applies per-IP rate limiting, a connection cap, brute-force lockout after repeated bad keys, an optional IP allowlist, and optional TLS. A lockfile in the data directory prevents two servers from corrupting the same data.