Documentation
NusaDB documentation
NusaDB is a single-node relational database engine written from scratch in Rust. These pages describe what the current release does, how to run it, and where its edges are.
The engine is usable and tested, but interfaces can still change between releases and some parts of a production story are missing. The limits page lists what is absent, including the ones that affect how much data you can load.
Where to start
If you have never run NusaDB, follow getting started: it covers the container image, building from source, connecting, and loading data in bulk. If you are deciding whether NusaDB fits a project, read the protocol note below and then the limits page. Between them they answer most evaluation questions faster than the feature list does.
| Page | What it covers |
|---|---|
| Getting started | Install, connect, a worked example, the shell, the drivers, adding a user, and the first errors you will meet. |
| SQL reference | Every type, statement and function the engine accepts, each with an example run against this release; error codes; where NusaDB chooses differently. |
| Transactions | Isolation levels, conflicts and the retry loop, aborted transactions, savepoints, locks, cursors. |
| Clients and protocol | Official drivers with install commands and snippets, connection settings, TLS and SCRAM, notifications. |
| Configuration | Every server flag, authentication and roles, memory limits and the page cache, the container image, systemd, TLS, metrics, checkpoints, backup, point-in-time recovery and standby. |
| Limits and capacity | What still has to fit in memory, log growth and checkpoints, restart time, backup and standby, one server per data directory, storage errors, and what is not built yet. |
How the engine is put together
Requests arrive over the Nusa wire protocol and pass through a parser, an analyzer that resolves names and checks types, a planner that chooses an execution strategy from collected statistics, and a vectorized executor that works on batches of rows.
Underneath, the storage engine is a clustered B-link/B+tree: rows live in the leaves, keyed by a row id the engine mints, so reaching a row by primary key does not need a second lookup in a separate heap. Row versions carry the transaction that created them and the transaction that removed them, which is what lets readers work from a snapshot without blocking writers. A background worker removes versions no snapshot can still see.
Durability comes from the write-ahead log. A record is written and made durable before a commit is acknowledged, each record carries a CRC32, and records are lz4-compressed. A checkpoint writes the pages changed since the last one into a new page segment and publishes an image naming every page, then truncates the log. On start-up the engine opens that image, loads pages from it as they are used, and replays only the log written after it.
| Layer | Responsibility |
|---|---|
| Client | nusadb-cli and the official drivers. |
| Protocol | Framing, TLS, SCRAM-SHA-256 authentication, extended query flow. |
| SQL engine | Parser, analyzer, planner and cost model, vectorized executor. |
| Transactions | Multi-version rows, no-wait locking, isolation levels, rollback. |
| Storage | Clustered B-link/B+tree, secondary indexes, version store, catalog, page cache with eviction and spill. |
| Log | Append-only write-ahead log with per-record checksums and compression, incremental checkpoints over immutable page segments, optional archive for point-in-time recovery. |
A note on the protocol
NusaDB implements its own wire protocol rather than another database's. Clients written for a different engine cannot connect: the server does not reply to a handshake it does not recognise, so from the client's side the socket simply appears dead. This is a design decision, not an unfinished feature.
The SQL dialect is separate from the wire format. Queries written against other engines
usually run unchanged once they reach NusaDB. What changes is how you connect. Use
nusadb-cli, one of the drivers listed under
clients, or implement the protocol yourself from its
specification.
Conventions in these pages
- Shell commands assume the release binaries are on your path or run from
./target/release/. - SQL examples are written for
nusadb-cliand end with a semicolon. - Measured numbers state the conditions they were measured under; where a figure depends on the host, that is said instead of quoting one.
- Anything described as planned is not in this release. Features are only listed as present when they are implemented and tested.
Getting help and reporting problems
Bugs and questions belong in the issue tracker. A report is most useful with the release or image digest, the statements that reproduce the behaviour, and what you expected instead. If the problem involves data size or restart time, include the size of the data directory. The limits page explains why that number matters more than the row count.