Choose the right integration model
ZeeDB can run embedded in a Go application, through the local CLI, or as a standalone HTTP server accessed from any language. Embedded and direct CLI usage require no daemon. The server owns the directory and shares its handle across requests.
| Concept | Current behavior |
|---|---|
| Database | One dedicated local filesystem directory |
| Owner | One process with one open handle for that directory |
| Callers | Multiple goroutines may share the handle |
| Namespace | A collection name inside the directory |
| Storage model | Opaque byte key/value records |
| Atomic unit | One single-shard mutation batch |
| Read visibility | One committed state per lookup or scan |
| Remote behavior | Authenticated HTTP access; no synchronization protocol |
Use separate directories for independent databases. Collections do not provide tenant authorization, encryption, or a security boundary.
Collections, keys, and values
A record is identified by (collection, key). Collection names contain 1–255 bytes and no NUL. A key contains at least one byte, can include NUL, and defaults to a 4096-byte maximum. A value may be empty.
The engine does not interpret JSON, validate application schemas, infer document IDs, or sort numeric-looking strings numerically. These are application responsibilities. Read data modeling before choosing a long-lived key encoding.
Commit sequence and record version
Every nonempty successful batch advances one database-wide sequence. A record’s Version is the sequence of the last batch that wrote it, not a record-local counter.
Two records written together share a version. A delete of an absent key still counts as a mutation and can advance the database sequence. An empty batch does not advance it.
The current API does not accept an expected version for a write. Reading a version then calling Put is not compare-and-swap. Prevent lost updates through application coordination when needed.
What atomic means
A batch is validated before WAL append, recorded as one frame, synced in durable mode, then published under the writer lock. Readers never observe half the batch.
Separate Get calls can observe separate commits. A Get followed by a Put is not a transaction. A scan holds a consistent state for that one call; pagination does not retain a snapshot across calls.
What durable means
The default Durable mode acknowledges after WAL sync. Supported process crashes preserve acknowledged durable commits, assuming the filesystem/device honors sync.
Relaxed skips per-commit sync. It may lose acknowledged writes. Close syncs both modes, but successful normal shutdown does not make earlier relaxed acknowledgements crash-safe retroactively.
A complete unacknowledged frame can recover. An I/O error after persistence starts is therefore an indeterminate outcome, not a rollback guarantee.
Current limits
The engine has one shard, one active memtable, and one consolidated table. Checkpointing is synchronous and rewrites the table while holding the writer lock. Startup verifies the table and replays the WAL.
No SQL parser, TTL, automatic secondary index, CAS, read/write transaction callback, persistent MVCC snapshot, live backup API, sync journal, or FastPath registration is available. The roadmap describes future proposals.
Suggested reading path
- Install and run the quickstart.
- Learn handle ownership and lifecycle.
- Choose key encodings and value schemas.
- Review concurrency and cancellation.
- Run the JSON, pagination, and worker lifecycle examples.
- Plan deployment, backups, and failure handling.