Quickstart

Create a database

With the CLI installed, initialize a directory:

zeedb init --data ./data

Open and CLI commands can create a new database directory. init makes that step explicit. Keep the directory on a local filesystem and let ZeeDB manage its contents.

Write a record

zeedb put --data ./data --collection users --key 1024 --value Ada

A collection is a namespace, a key is a nonempty byte string, and a value is an opaque byte string. This command stores Ada under key 1024 in users.

The default durability mode syncs the write-ahead log before acknowledging the write. Successful mutation commands do not print a result.

Read it back

zeedb get --data ./data --collection users --key 1024

The command writes the exact stored bytes, Ada, without adding a newline. A missing key produces an error on stderr and exits with code 1.

Explore a collection

zeedb put --data ./data --collection users --key 1025 --value Grace
zeedb scan --data ./data --collection users --limit 10
zeedb stats --data ./data

Scans return records in lexicographic key order as JSON. The Key and Value fields are base64, and Version is the record’s commit sequence.

Checkpoint and delete

zeedb flush --data ./data
zeedb delete --data ./data --collection users --key 1024

flush writes the memtable into a compacted SSTable. It is not necessary after every write: the WAL already provides durable recovery, and ZeeDB checkpoints automatically when configured buffer limits require it.

Deletes are idempotent, including when the key does not exist.

Try the embedded example

From the repository root:

go run ./examples/basic

The example uses a temporary database, commits two records in one atomic batch, reads a record, and scans the collection. It closes and removes its temporary database on exit.

One process owns a database directory at a time. Close the CLI or embedded handle before opening the same directory from another process.

Continue with the embedded Go guide or CLI reference.