Documentation / Clients and protocol

Clients and protocol

NusaDB implements its own wire protocol. This page covers what that means for integration, which drivers exist, and how to connect securely.

Its own protocol, deliberately

NusaDB does not implement another database's wire format. A client built for a different engine sends a handshake the server does not recognise, gets no reply, and eventually times out. From the client's side that looks like a dead socket rather than a refusal. This is by design.

Keep two things separate when planning an integration:

The wire format is NusaDB's own. Tools for other databases cannot connect, and no configuration changes that.
The SQL dialect is broadly familiar. Queries written for other engines usually run unchanged once they arrive over a NusaDB connection.

So porting an application means changing how it connects, not rewriting its SQL.

Official clients

Client	Notes
`nusadb-cli`	Interactive shell and batch runner; ships in the container image.
Rust	Synchronous and asynchronous APIs.
Java (JDBC)	Driver with `DatabaseMetaData` support for schema browsing tools.
Node.js	Promise-based client.
Python	DB-API client with a SQLAlchemy dialect.
Go	`database/sql` driver.
Ruby	Native client.
PHP	PDO-style client.
.NET	ADO.NET provider.

Two names changed recently

The shell is nusadb-cli and the bootstrap superuser is nusadb-root, matching the crate and the rest of the nusadb naming. Container images published before that change carry the older nusa-cli and nusa-root, so on an older image use those instead.

All of them carry data as the protocol's text form, which round-trips every type without loss. A binary result format exists on the server and is negotiated per column; drivers have not adopted it because text is already lossless and the gain is limited to prepared statements.

Connection settings

Setting	Default	Notes
Host and port	`127.0.0.1:5678`	One connection targets one database.
Database	`nusadb`	Cross-database queries are refused.
User	`nusadb-root`	The bootstrap superuser.
Authentication	trust-on-startup	SCRAM-SHA-256 once any credential is configured.
TLS	off	Enabled on the server with a certificate and key; the same port.

TLS and authentication

TLS runs on the same port: the server offers it when a certificate and key are configured, and a plaintext client is then refused. Because there is no system trust store in play, the client is told what to trust.

shell

nusadb-cli --host db.internal:5678 \
  --user app --database nusadb \
  --tls --tls-ca /etc/nusadb/ca.crt

A self-signed certificate is not automatically its own trust anchor

A certificate generated with the usual one-liner is marked as a certificate authority, and presenting it as a server certificate is rejected. Either create a separate CA and sign a server certificate with it, or generate a leaf certificate that is not marked as a CA.

Hostname verification is applied, and a mismatch reports which names the certificate covers. For mutual TLS, the server takes a client CA and then requires every client to present a certificate signed by it.

What SCRAM gives you

Passwords are never sent, in either direction: the exchange proves the client knows the password without transmitting it, and it also proves the server knows the stored verifier. A wrong password and an unknown user return the same authentication failure, so the error cannot be used to discover which usernames exist.

Bulk transfer

COPY moves rows in a single streaming exchange rather than a round trip per row, in both directions. The shell forms read from the command's standard input and write to its standard output, which makes them composable with ordinary Unix pipelines. See getting started.

Connections and pooling

The server handles connections on a thread pool rather than one process per connection, so a moderate number of idle connections is cheap. The default cap is 25 concurrent connections and excess connections queue rather than fail; raise --max-connections on a larger host. An external pooler is optional rather than a prerequisite.

PreviousTransactions NextConfiguration