nyxsql CLI reference

nyxsql is the repository's interactive multi-pane client. It requires Node.js 18 or newer and currently ships from source with the engine.

Install and connect

git clone https://github.com/NYXL-io/db.git
cd db/drivers/cli
npm ci

# Container endpoint
npm start -- --host 127.0.0.1 --port 7777

After npm link, invoke nyxsql directly.

nyxsql [--host <host>] [--port <port>] [--query <sql>]

-h, --host     server host; default 127.0.0.1
-p, --port     server port; default 7510
-q, --query    prefill the first pane; it does not execute automatically
    --help      show command and editing help

Query modes

• SELECT … and other ordinary statements run once and replace the result grid.
• STREAM SELECT … opens a live subscription. The pane applies the initial snapshot and then processes live changes until cancellation or termination.
• Table mode displays the maintained result. Changelog mode displays incoming insert, replace, update, remove, and move operations.

STREAM SELECT id, symbol, amount
FROM events
WHERE amount > 1000;

Timing and throughput

One-shot results separate server execution from client wall time:

3 rows · server 28µs · 2ms round-trip

The CLI first negotiates handshake schema 2. On that path, exact server time, numeric engine query identity, server identity, and prepared-plan cache state arrive beside the typed result; elapsed time and query ID are retained as bigint. An unsupported/no-row result uses compatible #meta plus TSV from the same captured execution, so the server never reruns SQL merely to change encoding.

If schema 2 is explicitly rejected, the CLI closes that socket and tries schema 1 on a fresh connection; a second rejection moves to plain TSV on another fresh connection. On a schema-1 binary connection, the CLI chooses bare OP_QUERY to preserve typed rows, so timing and numeric query ID are unavailable on that fallback. A malformed successful handshake is fatal rather than a downgrade signal.

Each one-shot owns one connection and a fresh nonzero 16-byte request ID. The ID correlates the response and is distinct from numeric query_id. A one-shot timeout closes the owning connection and relies on the engine's disconnect-cancellation checkpoints; this CLI revision exposes no one-shot cancel handle and does not send OP_CANCEL_REQUEST. Ctrl+C stops a focused live stream, not an in-flight one-shot. Shared stream metadata keeps one numeric query identity for the owner, late joiners, initial result, and subsequent updates.

Streams report the initial execution time and, when the peer supports metadata frames, the latest update time and update rate. server is prepare plus execute; round-trip includes the transport and client.

Key bindings

Failure behavior

A stream owns a connection. Ctrl+C, pane close, EOF, transport error, server shutdown, source drop, or a terminal engine error ends it. nyxsql does not claim cursor continuity after reconnect; rerun the statement to obtain and reconcile a new snapshot.

For a one-shot failure, inspect whether the request was read-only before repeating it. A lost DDL/DML response is ambiguous and should be reconciled against server state rather than retried blindly.

On the server, raw FIN/reset cancellation propagates through operator and storage-scan checkpoints and records NYXDB_EXEC_CANCELLED: client disconnected in system.query_log. Closing the CLI socket requests cooperative termination; it is not proof that mutation work was rolled back.

Compatibility and validation

The CLI uses the current experimental protocol and implements documented fallbacks for older operations. Keep it at the same source revision as the server for production-like use.

npm run typecheck
npm test
npm run render-test

# Against a running engine
npm run smoke
npm run smoke:v2

Read Drivers & protocol for application retry policy and Query identity, cancellation, and retries for request lifecycle, or Wire protocol for framing and negotiation.