Use nyxsql

nyxsql is NYXDB's experimental interactive terminal client. It provides a multi-pane SQL editor, tabular and changelog views, query history, server timing, and live STREAM SELECT subscriptions.

Install from the engine repository

The CLI requires Node.js 18 or newer and is not yet published as a standalone registry package.

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

Connect to the container image on port 7777:

npm start -- --host 127.0.0.1 --port 7777

Connect to a locally-built binary using its native default port 7510:

npm start -- --host 127.0.0.1 --port 7510

After npm link, the equivalent command is nyxsql --host 127.0.0.1 --port 7777. Run nyxsql --help for supported flags.

Run one-shot queries

Paste SQL into the focused pane and press Enter:

SELECT id, market, amount
FROM trades
ORDER BY id;

The footer separates server execution from client-observed wall time:

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

• server covers prepare and execute on the engine;
• round-trip includes transport and client overhead.

Use the difference diagnostically; neither number is a durability acknowledgement or a cross-node latency measurement.

Follow a stream

Streaming uses the required statement-prefix spelling:

STREAM SELECT id, market, amount
FROM trades
WHERE amount > 1000;

The pane enters a live state after the initial snapshot. Table mode maintains the current result; changelog mode exposes incoming insert, update, remove, and move operations. The client reports initial and update server timings when the peer supports metadata frames.

Work with panes

Bracketed multi-line paste is inserted as text rather than interpreted as terminal keypresses.

Disconnects and terminal errors

Each live stream owns its connection. Cancelling the pane closes the subscription. A socket error, server shutdown, dropped source, protocol error, or engine terminal error ends it; the client does not silently claim that a new connection resumes at the same cursor.

Each one-shot also owns its connection. A one-shot timeout closes that socket, and the engine observes FIN/reset cooperatively through query and storage checkpoints. The current CLI exposes no one-shot cancellation handle: Ctrl+C only stops a focused live stream, and the CLI does not send the separate OP_CANCEL_REQUEST wire operation. Its opaque 16-byte request ID correlates the response and is not the numeric engine query_id shown in query metadata and telemetry.

For automation around this pre-GA client:

1. treat a failed or closed stream as terminal;
2. decide at the application layer whether the query is safe to resubscribe;
3. reconnect with bounded backoff and jitter;
4. expect a new initial snapshot after resubscription; and
5. reconcile that snapshot before accepting live deltas.

One-shot queries may be retried after transport failure only when the caller knows the operation is safe to repeat. Do not automatically retry ambiguous DDL or DML responses: the server may have accepted the operation before the socket failed.

Version compatibility

The CLI prefers metadata and typed wire features supported by its revision and falls back where the protocol defines a downgrade. That behavior is not a GA compatibility promise. Pin the CLI and server to the same source SHA for production-like testing and run the CLI's protocol smoke tests when upgrading.

See Query identity, cancellation, and retries for the exact schema-2, disconnect, and retry contract.

See nyxsql reference and the wire protocol for the exact current contracts.