NusaDB

Documentation / Getting started

Getting started

Run a server, connect to it, and load some data. Two installation routes are covered: the published container image, and a build from source.

Run the container image

The image carries both the server and the shell, so nothing needs building. Give it a volume: the data directory holds the write-ahead log, which is the durable copy of your data.

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

Setting NUSADB_USER together with NUSADB_PASSWORD turns on SCRAM-SHA-256 for that user. Setting only one of the pair is an error, so a half-configured container fails at start-up instead of quietly accepting everyone.

Without credentials the server trusts every client

A server started with no --auth-user and no environment pair runs trust-on-startup: any client is accepted without a password, and the startup log says so. That is fine for a laptop and wrong for anything reachable by others.

Build from source

A Rust toolchain is the only prerequisite; the pinned version lives in rust-toolchain.toml and is installed automatically by rustup.

shell
git clone https://github.com/nusadb/nusadb.git
cd nusadb
cargo build --release

./target/release/nusadb-server \
  --listen 127.0.0.1:5678 \
  --data-dir ./data

The data directory is created if it does not exist. RUST_LOG controls log verbosity, for example RUST_LOG=info.

Connect

The defaults are host 127.0.0.1:5678, database nusadb, and the bootstrap superuser nusadb-root. A trust-on-startup server ignores the password; a server configured with credentials requires it.

shell
nusadb-cli --host 127.0.0.1:5678 --user nusadb-root --database nusadb

# inside the container
docker exec -it nusadb nusadb-cli --user app --database nusadb
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.

Clients for other databases will not connect

NusaDB speaks its own protocol. A tool built for a different engine gets no answer to its handshake, which looks like a dead socket from its side. Use nusadb-cli, one of the official drivers, or write a client against the specification. See clients and protocol.

Create something

sql
CREATE TABLE customers (
  id      BIGINT PRIMARY KEY,
  email   TEXT NOT NULL UNIQUE,
  country TEXT,
  joined  TIMESTAMPTZ DEFAULT now()
);

CREATE INDEX customers_country ON customers (country);

INSERT INTO customers (id, email, country)
VALUES (1, 'ana@example.com', 'ID'),
       (2, 'budi@example.com', 'ID')
RETURNING id, joined;

Databases and schemas

NusaDB holds several databases, each with its own directory under <data-dir>/base/, and several schemas within a database. Each connection targets one database.

sql
CREATE DATABASE app;              -- a separate physical database
CREATE SCHEMA tenant;               -- a namespace inside this database
CREATE TABLE tenant.t (id INT);
SELECT * FROM tenant.t;           -- resolved through search_path, then public

Connect to another database by name; a session cannot query across databases.

shell
nusadb-cli --host 127.0.0.1:5678 --user nusadb-root --database app

Load and export in bulk

COPY streams rows in one exchange instead of a round trip per row. In the shell forms the data travels on the command's own standard input and output.

shell
# tab-delimited, \N for NULL (the server's text format)
nusadb-cli -c "COPY customers FROM STDIN" < rows.tsv

# CSV with a header line
nusadb-cli -c "COPY customers FROM STDIN WITH (FORMAT csv, HEADER)" < rows.csv

# export the same way
nusadb-cli -c "COPY customers TO STDOUT" > rows.tsv

During an export the row count goes to standard error, so it never lands in the exported file. One redirect feeds one load: a batch containing two COPY … FROM STDIN statements refuses the second rather than reporting that it loaded nothing. Typing COPY … FROM STDIN at the interactive prompt is refused too, because there the keyboard is already the session's input.

Running statements from scripts

Both batch forms behave the same way: -c takes a statement and -f takes a file. A server error is printed to standard error and the remaining statements still run. The process then exits non-zero, so a shell script that loads data in stages stops at the failed stage instead of continuing as though it had worked.

shell
set -eu
nusadb-cli -f schema.sql
nusadb-cli -c "COPY customers FROM STDIN" < customers.tsv
nusadb-cli -c "ANALYZE customers"    # refresh planner statistics after a load

Next

PreviousOverview NextSQL reference