Wire protocol
The NYXDB wire protocol — framing, operation codes, TSV result payloads, streaming deltas, and the binary columnar path.
Clients connect over TCP and exchange length-prefixed binary frames. The current protocol (v1) carries SQL in the request and TSV in the response.
Framing
Request: [op:1][uuid:16][len:4 BE][sql:len bytes UTF-8]
Response: [uuid:16][status:1][len:4 BE][payload:len bytes UTF-8]The 16-byte UUID correlates a response with its request. Lengths are big-endian 32-bit.
Operation codes
| Op | Value | Purpose |
|---|---|---|
OP_QUERY | 0x02 | One-shot query; one TSV response block |
OP_STREAM | 0x03 | Streaming query; TSV frames until cancelled |
OP_QUERY_META | 0x04 | Like OP_QUERY, plus a #meta timing line |
OP_STREAM_META | 0x05 | Like OP_STREAM, plus STATUS_META frames |
OP_QUERY_PARAMS | 0x06 | Parameterized query: sql ('\0' param)* |
OP_STREAM_PARAMS | 0x07 | Parameterized stream; params bind $n |
Status codes
| Status | Value | Meaning |
|---|---|---|
STATUS_OK | 0x00 | Success; payload is TSV (or empty) |
STATUS_SNAPSHOT | 0x02 | Streaming: full current result (client replica) |
STATUS_DELTA | 0x03 | Streaming: positional diff operations |
STATUS_META | 0x04 | Timing frame: #meta\telapsed_us=<n>[\tserver=<id>] |
Result payload (TSV)
market amount
BTC-USD 4120
ETH-USD 2880The first row is column names; each subsequent row is tab-separated UTF-8 cells.
A #meta line (from the *_META ops) reports server-side elapsed_us.
Streaming deltas
Under STATUS_DELTA, the payload is a batch of positional operations that mutate
the client's snapshot:
| Op line | Meaning |
|---|---|
I\t<row>\t<v1>\t<v2>… | Insert a row at position |
V\t<row>\t<v1>\t<v2>… | Replace the row at position |
U\t<row>\t<col>\t<value> | Update one cell |
R\t<row> | Remove the row at position |
M\t<from>\t<to> | Move a row |
This is what the CLI's changelog mode (Ctrl+O) renders directly.
Binary columnar path
For high-throughput ingestion, the engine defines a binary columnar INSERT path (ADR-045, Accepted) — columns are sent as typed blocks rather than row TSV.
TODO-verify: a v2 columnar result protocol (binary result frames built from bound columns, with a capability handshake) is in active development in the engine. It is not yet covered by a published ADR (there is no ADR-081 in the repo as of writing), so treat its framing as unstable and confirm against your release before implementing a client against it. The v1 TSV protocol above is the stable current contract.
Ports
Dev builds commonly listen on 7510; the container image defaults to 7777.