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, run, connect, create a database, load and export data. |
| SQL reference | Types, statements, functions, and the query features the engine accepts. |
| Transactions | Isolation levels, snapshot behaviour, conflicts and retries, savepoints. |
| Clients and protocol | Official drivers, connection settings, and the wire protocol shape. |
| Configuration | Server flags, resource defaults, authentication, TLS, metrics. |
| Limits and capacity | Memory-bound data size, log growth, restart time, 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. On start-up the engine replays the log to rebuild state.
| 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. |
| Log | Append-only write-ahead log with per-record checksums and compression. |
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.