Drivers & protocol
Choose a NYXDB client and design explicit connection, retry, streaming-termination, and version-compatibility behavior for the pre-GA wire protocol.
NYXDB exposes one transport-independent request envelope over raw TCP and WebSocket. The CLI, JDBC driver, and web console are functional clients for that contract. All client transports are experimental: pin compatible revisions and test every upgrade against the exact server artifact.
The engine listener has no native TLS or public Origin policy. Use
--require-auth on every browser-facing or otherwise untrusted listener and
place raw TCP/ws:// behind a reviewed trusted-network edge. End-user auth
providers do not close the default-open operator path by themselves.
nyxsql CLI
Interactive multi-pane terminal client for one-shot and live queries.
JDBC
Java 17 driver with one-shot SQL, metadata, prepared statements, and negotiated typed results.
Web console
Static browser UI that connects directly over WebSocket.
Browser endpoint client
Implement auth, typed-parameter endpoint calls, live subscriptions, revocation, and reconnect without assuming an SDK.
Query lifecycle
Keep request, query, and subscription identity distinct; cancel work and retry safely.
Wire protocol
Experimental envelopes, operations, v1/v2 negotiation, streaming, and block ingest.
Choose a client
| Client | Use it for | Default endpoint | Status |
|---|---|---|---|
nyxsql | Interactive development, concurrent panes, stream inspection, timing | 127.0.0.1:7510 | Experimental |
| JDBC | Java applications, forward-only results, prepared statements, catalog metadata | jdbc:nyxdb://127.0.0.1:7510/ | Experimental |
| Web console | Browser-based SQL and operational inspection | ws://127.0.0.1:7777 | Experimental |
| Browser/platform endpoint client | Controlled read-only access to published queries; no shipped SDK | WebSocket on the server port, behind a reviewed edge for untrusted clients | Experimental |
| Custom client | Controlled integrations that can track the current engine revision | Raw TCP or WebSocket on the server port | Experimental |
The container listens on 7777; a native server defaults to 7510. Explicitly
configure the endpoint instead of relying on those different defaults.
Current operator-auth coverage is not uniform. The web console replays
OP_AUTH on every socket. This revision of nyxsql and the JDBC driver does not
expose operator-credential configuration and therefore cannot run queries
against --require-auth. Do not disable the production gate to accommodate a
client; use the console or a reviewed custom authenticated client until the
chosen driver revision implements operator auth.
Connection lifecycle
A production-quality integration should make each stage observable:
- Pin compatibility. Record the engine source SHA and the driver revision.
- Connect with a deadline. Bound connection establishment and frame reads; the server also enforces handshake, idle, frame, and write deadlines.
- Negotiate once per connection. A v2-capable client may send the capability operation. A client that does not negotiate remains on v1 TSV.
- Probe the transport. Use the wire ping operation where supported. It does not execute SQL or create query telemetry.
- Authenticate the intended plane. Use operator auth for database tooling or provider/token auth for an endpoint client. Authenticate once on every fresh socket; do not reuse a socket to change principals.
- Correlate responses. Match the 16-byte request ID and treat protocol mismatches as connection-fatal. Correlation bytes do not authorize arbitrary same-socket multiplexing; the server executes ordinary requests sequentially per connection.
- Close deliberately. Cancelling a stream closes that subscription; closing a connection must fail its in-flight operations.
Retry rules
Retries belong to the application because a network error alone cannot prove whether a statement ran.
| Outcome | Recommended behavior |
|---|---|
| Connection refused before a request is sent | Retry with a bounded exponential backoff, jitter, and an overall deadline. |
One-shot SELECT loses its connection before a response | Retry only if the application accepts repeating the read and can discard the abandoned result. |
| DDL or DML loses its connection before a response | Treat the outcome as ambiguous. Reconcile state or use an application idempotency strategy before repeating it. |
| Server returns an error frame | Surface the diagnostic; do not convert a deterministic SQL/protocol error into a transport retry loop. |
| Capability operation is explicitly unsupported | Close that connection and perform the documented downgrade on a fresh socket. |
| Malformed or contradictory negotiation | Fail the connection; do not guess a format. |
| Stream closes or receives a terminal error | Mark that subscription terminated. If policy permits, create a new subscription and reconcile its new initial snapshot. |
Streaming termination
STREAM SELECT produces an initial snapshot followed by live updates. The
current release does not promise a resumable cursor across connections. A
client must consider cancellation, EOF, transport failure, server shutdown,
source drop, and a terminal error frame to be final for that subscription.
When resubscribing, assume the server will send a new snapshot. Apply it as a replacement boundary before processing new deltas; do not append it to stale client state.
Version compatibility
Wire v1 is the unnegotiated compatibility mode and wire v2 is an opt-in, per-connection typed format. Handshake schema 2 can additionally carry exact timing, engine query identity, cache state, and server identity beside a typed result. The capability handshake prevents a silent misdecode and lets current clients fall back when an older server explicitly does not recognize negotiation.
That mechanism is not a GA compatibility guarantee. Before upgrading:
- pair the driver and server in a staging environment;
- run one-shot, parameterized, streaming, cancellation, malformed-frame, and downgrade tests;
- verify type fidelity for decimal, temporal, nullable, low-cardinality, and vector columns; and
- retain the old artifact until recovery and rollback are proven.
See Capabilities & status for the release boundary.