nusadb/nusadb repository overview

⁠NusaDB

NusaDB is a relational database engine built from scratch in Rust a clustered B-link/B+tree storage engine with MVCC, WAL-based crash recovery, a full SQL surface (parser, analyzer, planner, vectorized executor).

⁠Supported tags

• latest — the current release; what the examples below use.

⁠Supported drivers

• https://docs.rs/nusadb/latest/nusadb⁠
• https://mvnrepository.com/artifact/com.nusadb⁠
• https://packagist.org/packages/nusadb/nusadb⁠
• https://www.piwheels.org/project/nusadb⁠
• https://pkg.go.dev/github.com/nusadb/go⁠
• https://rubygems.org/gems/nusadb⁠
• https://www.npmjs.com/package/nusadb⁠

⁠Quick reference

• Where to get help: https://github.com/nusadb/nusadb⁠ issues (see repo for link) — file bugs and questions there.
• Base image: Debian 12 (bookworm)
• Architectures: linux/amd64
• Exposed ports: 5678/tcp (wire protocol), 9100/tcp (Prometheus metrics, opt-in)
• Data volume: /var/lib/nusadb

⁠What is NusaDB?

NusaDB implements the classic 7-layer database stack — client, wire protocol, SQL engine (parser → analyzer → planner → executor), transaction layer (MVCC + lock manager), storage engine (clustered B-link/B+tree), WAL, and physical storage — as a single Rust binary. It speaks its own Nusa Wire Protocol with SCRAM-SHA-256 authentication and optional TLS/mTLS, and ships an interactive SQL shell (nusa-cli) alongside the server.

⁠How to use this image

⁠Start a server

docker run -d \
  --name nusadb \
  -p 5678:5678 \
  -v nusadb-data:/var/lib/nusadb \
  nusadb/nusadb:latest

By default the server listens on 0.0.0.0:5678, stores data in /var/lib/nusadb, and runs trust-on-startup (no password) — fine for local development, not for anything reachable outside your machine.

⁠Connect with the bundled SQL shell

docker exec -it nusadb nusa-cli --user nusa-root --database nusadb

Or from the host, using a local install of nusa-cli:

nusa-cli --host 127.0.0.1:5678 --user nusa-root --command "SELECT version();"

⁠Connect from an application (DataGrip, JDBC, drivers)

Point any NusaDB client at the wire-protocol port. The connection URL is:

jdbc:nusadb://<host>:<port>/<database>

• host — where the container is reachable (localhost when published locally).
• port — the host port you published. The server listens on 5678 inside the container, so -p 5678:5678 → use 5678. If you mapped a different host port, use that one (e.g. -p 5433:5678 → use 5433).
• database — the default database is nusadb.
• user / password — default superuser nusa-root (whatever you set via NUSADB_USER / NUSADB_PASSWORD; omit both for a trust-on-startup server).

DataGrip / DBeaver / any JDBC tool — install the JDBC driver (com.nusadb:nusadb-jdbc⁠), then use a URL such as:

jdbc:nusadb://localhost:5678/nusadb      # default port (-p 5678:5678)
jdbc:nusadb://localhost:5433/nusadb      # if you published -p 5433:5678

In DataGrip: New → Data Source → (add the nusadb-jdbc driver) → URL = one of the above, then set the user/password.

Native drivers (Rust / Python / Node / Go / PHP / Ruby — see “Supported drivers” above) use the nusadb:// URL scheme:

nusadb://nusa-root:PASSWORD@localhost:5678/nusadb

⁠Enable authentication

Set NUSADB_USER / NUSADB_PASSWORD (canonical superuser is nusa-root) to require SCRAM-SHA-256 auth instead of trust-on-startup:

docker run -d \
  --name nusadb \
  -p 5678:5678 \
  -e NUSADB_USER=nusa-root \
  -e NUSADB_PASSWORD=change-me \
  -v nusadb-data:/var/lib/nusadb \
  nusadb/nusadb:latest

⁠First-run SQL initialization

Mirroring the Postgres image convention: on a fresh (empty) data directory, any *.sql files mounted at /docker-entrypoint-initdb.d are executed in lexical order once the server is ready. This does not re-run against an existing data directory.

docker run -d \
  --name nusadb \
  -p 5678:5678 \
  -v nusadb-data:/var/lib/nusadb \
  -v ./init:/docker-entrypoint-initdb.d \
  nusadb/nusadb:latest

-- ./init/01-schema.sql
CREATE DATABASE app;
CREATE SCHEMA tenant;
CREATE TABLE tenant.users (id UUID PRIMARY KEY, email TEXT NOT NULL);

⁠Enable TLS

docker run -d \
  --name nusadb \
  -p 5678:5678 \
  -v nusadb-data:/var/lib/nusadb \
  -v ./certs:/certs \
  nusadb/nusadb:latest \
  --tls-cert /certs/server.pem --tls-key /certs/server-key.pem

Add --tls-client-ca /certs/ca.pem to require mutual TLS.

⁠Expose Prometheus metrics

docker run -d \
  --name nusadb \
  -p 5678:5678 -p 9100:9100 \
  -v nusadb-data:/var/lib/nusadb \
  nusadb/nusadb:latest \
  --metrics-listen 0.0.0.0:9100

⁠docker-compose example

services:
  nusadb:
    image: nusadb/nusadb:latest
    ports:
      - "5678:5678"
    environment:
      NUSADB_USER: nusa-root
      NUSADB_PASSWORD: change-me
    volumes:
      - nusadb-data:/var/lib/nusadb
      - ./init:/docker-entrypoint-initdb.d

volumes:
  nusadb-data:

⁠Environment variables

⁠Notable nusadb-server flags

Pass these after the image name (they extend/override the image's default CMD):

Run docker run --rm nusadb/nusadb:latest --help for the full list.

⁠Data persistence

All durable state (WAL + data files) lives under /var/lib/nusadb. Mount a named volume or bind mount there to persist data across container restarts/upgrades.

⁠License

See the project repository for license terms.