Clients
nonodb has thin official clients for Python, Rust, Node.js, and Go. They all speak the same HTTP/JSON API and keep no state beyond one HTTP connection. The daemon remains responsible for queries, indexes, updates, search, and transactions.
| Language | Location | Style | Unix socket | TCP/TLS | mTLS |
|---|---|---|---|---|---|
| Python | client/nonodb.py |
sync | yes | yes | yes |
| Rust | nonodb-client |
sync | yes (Unix) | yes | yes |
| Node.js | client/node |
async / Promise | yes (Unix) | yes | yes |
| Go | client/go |
context-aware | yes (Unix) | yes | yes |
Common configuration
Section titled “Common configuration”On Linux and macOS the clients use the Unix socket by default. Set
NONODB_SOCK to change the path. A base URL switches a client to TCP/TLS:
export NONODB_SOCK=/run/nonodb.sock # default Unix socketexport NONODB_TOKEN='nodb_...' # required for TCP unless mTLS identifies youexport NONODB_DB=app1 # optional database inside one daemon# or:export NONODB_URL=https://127.0.0.1:7878export NONODB_TLS_CA=/etc/nonodb/ca.crtexport NONODB_TLS_VERIFY=1Mutual TLS uses the same three variables in every client:
export NONODB_TLS_CLIENT_CERT=/etc/nonodb/client.crtexport NONODB_TLS_CLIENT_KEY=/etc/nonodb/client.keyNONODB_TLS_VERIFY=0 disables certificate verification and must only be used
for local development. See Mutual TLS for a complete mTLS setup,
revocation, and rotation guide.
Windows has no Unix socket listener in the daemon. Use a base URL and TCP there.
TCP always requires an auth registry. Use NONODB_TOKEN, a registered client
certificate, or both (they must resolve to the same principal). The Unix socket
does not require a token and maps to the local administrative principal.
All clients return a typed error for daemon errors (ok: false). Read
operations are retried after a transport failure. Writes are never retried after
an ambiguous transport error or 5xx, because the write may have committed and
only the response was lost. Use write_batch when several writes must succeed
or fail together.
Routing writes to the primary
Section titled “Routing writes to the primary”A replica rejects writes with HTTP 403 and error.code = "read_only". The
response includes the current primary in the Location header and in
error.write_url. Clients can use a custom write endpoint, or discover it from
the replica automatically:
export NONODB_WRITE_URL=https://primary.internal:7878export NONODB_AUTO_PRIMARY=1export NONODB_TOKEN='nodb_...'When write_url is configured, reads keep using the socket/base URL and writes
go directly to the primary. When auto_primary is enabled, the client reads
/readyz.replication.write_url; if a stale write endpoint still answers
read_only, the client retries that single write once against the advertised
primary.
A retry only happens after an explicit 403 read_only, which guarantees the
replica did not apply the write. It never happens after a timeout, a connection
error, or 5xx. The primary endpoint normally requires a bearer token, so a
Unix-socket client must also be given NONODB_TOKEN or token/WithToken to
write remotely.
db = NonoDB( "/run/nonodb.sock", # reads from the local replica write_url="https://primary.internal:7878", token="nodb_...", auto_primary=True, # or omit write_url and discover it)let db = Client::builder() .socket_path("/run/nonodb.sock") .write_url("https://primary.internal:7878") .token("nodb_...") .auto_primary(true) .build()?;const db = new NonoDB({ socketPath: '/run/nonodb.sock', writeUrl: 'https://primary.internal:7878', token: 'nodb_...', autoPrimary: true,});db := nonodb.New( nonodb.WithSocketPath("/run/nonodb.sock"), nonodb.WithWriteURL("https://primary.internal:7878"), nonodb.WithToken("nodb_..."), nonodb.WithAutoPrimary(true),)Cursor operations (cursor_find, cursor_aggregate, get_more,
close_cursor) and subscriptions stay on the node that created them; route
those workloads to the same node. A mixed batch containing any write is sent
to the primary as a whole.
Databases
Section titled “Databases”One daemon can host several independent databases. Every official client accepts
an explicit database and falls back to NONODB_DB, then default. Requests are
routed to /<database>/v1/exec; default may also use /v1/exec.
db = NonoDB("/run/nonodb.sock", database="app1")let db = Client::builder() .socket_path("/run/nonodb.sock") .database("app1") .build()?;const db = new NonoDB({ socketPath: '/run/nonodb.sock', database: 'app1' });db := nonodb.New( nonodb.WithSocketPath("/run/nonodb.sock"), nonodb.WithDatabase("app1"),)Database names are case-sensitive and are not collections. Collections, indexes, subscriptions, history, TTL, and events are isolated per database. There are no cross-database queries, transactions, or joins. See Multiple databases for routing, management, limits, and backup commands.
Clients send dates as Extended JSON objects. Convert native datetimes to an
RFC 3339 string with Z or a numeric offset before calling the client:
{"at": {"$date": "2026-01-01T01:00:00+01:00"}}Epoch milliseconds are also accepted. The daemon normalizes the value to
canonical UTC milliseconds. Filter with the same representation and normal
operators ($gte, $lt, …); see Dates and time zones.
Numbers and decimals
Section titled “Numbers and decimals”Send Decimal128 values as Extended JSON objects; no client-side decimal conversion is required:
{"price": {"$numberDecimal": "199.99"}}Use the same form in filters and update values. Ordinary JSON integers and
floats participate in the same numeric bracket. For NaN and Infinity, use
{"$numberDouble": "NaN"} or {"$numberDouble": "Infinity"}. Integer forms
{"$numberInt": "42"} and {"$numberLong": "9007199254740993"} are accepted.
See Numbers and decimals.
Binary, UUID, and ObjectId
Section titled “Binary, UUID, and ObjectId”Send binary, UUID, and ObjectId values as Extended JSON objects:
{"payload": {"$binary": {"base64": "YQ==", "subType": "00"}}}{"payload": {"$uuid": "00112233-4455-6677-8899-aabbccddeeff"}}{"ref": {"$oid": "000000000000000000000001"}}Use the same form in filters. $uuid is canonicalized to binary subtype 04.
Query types with {"$type": "binData"} or {"$type": "objectId"}. See
BSON scalar types.
Regular expressions
Section titled “Regular expressions”Use $regex with optional $options:
users.find({"name": {"$regex": "^ada", "$options": "i"}})users.find({"tags": {"$regex": "^rus"}})Only string values match; arrays are checked element by element. Invalid
patterns/options return invalid_query. See API filters.
Arrays
Section titled “Arrays”Array filters use the normal MongoDB operators:
items.find({"tags": {"$all": ["rust", "lmdb"]}})items.find({"tags": {"$size": 2}})items.find({"items": {"$elemMatch": {"sku": "x", "qty": {"$gt": 5}}}})Malformed operator arguments return invalid_query. Arrays are supported by
multikey secondary indexes; $size still requires a scan.
Python
Section titled “Python”The Python client is documented separately in Python client.
from nonodb import NonoDB
with NonoDB("/run/nonodb.sock") as db: users = db.collection("users") users.insert({"name": "Ada", "age": 36}) print(users.find({"age": {"$gte": 18}})) print(users.aggregate([ {"$group": {"_id": "$tenant", "n": {"$sum": 1}}}, ]))Add the client from this repository:
[dependencies]nonodb-client = { git = "https://github.com/essmos/nonodb", package = "nonodb-client" }serde_json = "1"use nonodb_client::{Client, FindQuery};use serde_json::json;
fn main() -> Result<(), Box<dyn std::error::Error>> { let db = Client::unix("/run/nonodb.sock")?; // TCP/TLS alternative: // let db = Client::builder() // .base_url("https://127.0.0.1:7878") // .token("secret") // .build()?;
let users = db.collection("users"); let id = users.insert(&json!({"name": "Ada", "age": 36}))?; let query = FindQuery::new(json!({"age": {"$gte": 18}})) .sort("age", -1) .limit(10); let adults = users.find(&query)?; let rows = users.aggregate(&[ json!({"$group": {"_id": "$tenant", "n": {"$sum": 1}}}), ])?; println!("{id}: {adults:?} {rows:?}"); Ok(())}The Rust client exposes exec, batch, write_batch, lookup, get_many,
history, aggregation, indexes, text search, fuzzy search, vector search, and
online map resize.
Client::from_env() reads NONODB_SOCK,
NONODB_URL, NONODB_TOKEN, NONODB_DB, NONODB_TLS_VERIFY,
NONODB_TLS_CA, NONODB_TLS_CLIENT_CERT, and NONODB_TLS_CLIENT_KEY. For
mTLS:
let db = Client::builder() .base_url("https://127.0.0.1:7878") .ca_cert("/etc/nonodb/ca.crt") .client_cert("/etc/nonodb/client.crt", "/etc/nonodb/client.key") .build()?;Node.js
Section titled “Node.js”The Node client has no runtime dependencies and requires Node 18 or newer. It is not yet published to npm; install it from this repository:
npm install /path/to/nonodb/client/nodeconst { NonoDB } = require('nonodb-client');
async function main() { const db = new NonoDB(); // NONODB_SOCK/NONODB_URL and NONODB_DB const users = db.collection('users');
const id = await users.insert({ name: 'Ada', age: 36 }); const adults = await users.find( { age: { $gte: 18 } }, { sort: [['age', -1]], limit: 10, comment: 'dashboard', maxTimeMS: 5000, hint: 'age', }, ); const total = await users.count({}, { maxTimeMS: 5000 }); console.log(id, adults, total); db.close();}
main().catch(console.error);For TCP/TLS or mTLS:
const db = new NonoDB({ baseUrl: 'https://127.0.0.1:7878', token: 'secret', verify: true, caCert: '/etc/nonodb/ca.crt', clientCert: '/etc/nonodb/client.crt', clientKey: '/etc/nonodb/client.key',});go get github.com/essmos/nonodb/client/go@mainpackage main
import ( "context" "fmt"
nonodb "github.com/essmos/nonodb/client/go")
func main() { ctx := context.Background() db := nonodb.New() // NONODB_SOCK/NONODB_URL and NONODB_DB users := db.Collection("users")
id, err := users.Insert(ctx, map[string]any{"name": "Ada", "age": 36}) if err != nil { panic(err) }
adults, err := users.Find(ctx, nonodb.FindQuery{ Filter: map[string]any{"age": map[string]any{"$gte": 18}}, Sort: []nonodb.SortField{{Field: "age", Direction: -1}}, }) if err != nil { panic(err) } fmt.Println(id, adults)}TCP/TLS or mTLS:
db := nonodb.New( nonodb.WithBaseURL("https://127.0.0.1:7878"), nonodb.WithToken("secret"), nonodb.WithTLSVerify(true), nonodb.WithTLSCA("/etc/nonodb/ca.crt"), nonodb.WithTLSClientCert("/etc/nonodb/client.crt", "/etc/nonodb/client.key"),)The Go client methods take a context.Context; use it for cancellation and
deadlines. FindQuery also accepts Comment, MaxTimeMS, and Hint; use
CountWithOptions, AggregateWithOptions, and FindOneWithOptions for the
corresponding read options. Exec is available for operations not covered by a
convenience method.
Write durability
Section titled “Write durability”All write payloads accept an optional durability field:
{"op":"insert_many","coll":"imports","docs":[...],"durability":"relaxed"}Python helpers expose it directly:
users.insert(doc, durability="relaxed")users.insert_many(docs, durability="relaxed")users.update(filter, {"$set": {"x": 1}}, durability="full")db.write_batch(ops, durability="relaxed")users.aggregate([{"$merge": {"into": "totals"}}], durability="relaxed")db.sync()Clients classify a terminal $out or $merge aggregation as a write and route
it to the primary automatically. Rust, Node.js, and Go clients can send the same
field through their normal exec/Exec payload. full is the default. unsafe requires
NONODB_ALLOW_UNSAFE_WRITES=1 on the daemon. See
Write durability for guarantees and risks.
Batch lookups
Section titled “Batch lookups”lookup fetches documents by _id or a unique index in one request,
preserving input order and returning null for missing keys. It is the
recommended replacement for N separate find_one calls. A non-_id lookup
requires a unique index. by may be an array for a compound unique index; each
value must then be an array in the same field order.
Python:
articles.create_index("slug", unique=True, include=["title", "status"])
docs = articles.lookup( "slug", ["async-rust", "missing", "lmdb"], fields=["title", "status"],)# [doc, None, doc]
article = articles.lookup_one("slug", "async-rust", projection={"title": 1})ids = articles.get_many(["a", "b", "missing"])
# Compound unique index: tenant_id + slug.articles.create_index(fields=["tenant_id", "slug"], unique=True)rows = articles.lookup( ["tenant_id", "slug"], [["acme", "async-rust"], ["other", "async-rust"], ["acme", "missing"]],)Rust:
use serde_json::json;
let slugs = vec!["async-rust", "missing", "lmdb"];let docs = articles.lookup( "slug", &slugs, Some(&["title".to_string(), "status".to_string()]),)?;let article = articles.lookup_one( "slug", &"async-rust", None,)?;
// Compound lookup or a projection excluding `_id`.let keys = vec![json!(["acme", "async-rust"]), json!(["acme", "missing"])];let rows = articles.lookup_with( &["tenant_id", "slug"], &keys, None, Some(&json!({"title": 1, "_id": 0})),)?;let ids = articles.get_many(["a", "b", "missing"])?;Node.js:
await articles.createIndex('slug', { unique: true, include: ['title', 'status'] });
const docs = await articles.lookup('slug', ['async-rust', 'missing', 'lmdb'], { fields: ['title', 'status'],});const article = await articles.lookupOne('slug', 'async-rust', { projection: { title: 1, _id: 0 },});const ids = await articles.getMany(['a', 'b', 'missing']);
await articles.createIndex(['tenant_id', 'slug'], { unique: true });const rows = await articles.lookup( ['tenant_id', 'slug'], [['acme', 'async-rust'], ['other', 'async-rust'], ['acme', 'missing']],);Go:
_, err := articles.CreateIndex(ctx, []string{"slug"}, nonodb.IndexOptions{ Unique: true, Include: []string{"title", "status"},})
docs, err := articles.Lookup(ctx, "slug", []any{ "async-rust", "missing", "lmdb",}, nonodb.LookupOptions{Fields: []string{"title", "status"}})
article, err := articles.LookupOne(ctx, "slug", "async-rust", nonodb.LookupOptions{ Projection: map[string]any{"title": 1, "_id": 0},})ids, err := articles.GetMany(ctx, []string{"a", "b", "missing"})
_, err = articles.CreateIndex(ctx, []string{"tenant_id", "slug"}, nonodb.IndexOptions{ Unique: true,})rows, err := articles.Lookup(ctx, []string{"tenant_id", "slug"}, []any{ []any{"acme", "async-rust"}, []any{"other", "async-rust"}, []any{"acme", "missing"},}, nonodb.LookupOptions{})Shared rules:
bydefaults to_id.valuesis capped at 10,000 per request; the result budget is 64 MiB (result_too_large).- Missing or malformed compound values become
null;get_manykeeps its old behavior and filters them out. fieldsis a top-level inclusive projection.projectionaccepts a normal flat projection, can exclude_id, and cannot be combined withfields. With a covering index, an inclusive projection avoids reading the document.- Duplicate input keys produce duplicate results. Repeated keys are looked up only once internally.
lookupis not a join and does not accept a filter or sort; usefindfor arbitrary predicates. Non-unique lookups are not supported yet.
See HTTP API: lookup for the wire format.
SQL returns an array of result objects. Parameters are positional; use ? or
$1 placeholders. SELECT is read-only; INSERT, UPDATE, and DELETE use the single
writer and return inserted/inserted_ids, matched/modified, or
deleted. UPDATE SET supports document expressions. explain_sql returns
the selected SELECT plan. See SQL queries for the full
grammar and limitations.
Python:
rows = db.sql( "SELECT DISTINCT team FROM users WHERE age >= $1 ORDER BY team", [18],)plan = db.explain_sql( "SELECT team, COUNT(*) AS n FROM users GROUP BY team HAVING COUNT(*) > 1")inserted = db.sql( "INSERT INTO users (name, age) VALUES ($1, $2)", ["Ada", 36],)updated = db.sql( "UPDATE users SET age = age + 1 WHERE name = $1", ["Ada"],)deleted = db.sql("DELETE FROM users WHERE age < $1", [18])Rust:
let rows = db.sql( "SELECT team, COUNT(*) AS n FROM users GROUP BY team HAVING COUNT(*) > $1", &[json!(1)],)?;let plan = db.explain_sql("SELECT * FROM users WHERE age >= $1", &[json!(18)])?;let inserted = db.sql( "INSERT INTO users (name, age) VALUES ($1, $2)", &[json!("Ada"), json!(36)],)?;Node.js:
const rows = await db.sql( "SELECT DISTINCT team FROM users GROUP BY team HAVING COUNT(*) > 1",);const plan = await db.explainSql('SELECT * FROM users WHERE age >= $1', [18]);const inserted = await db.sql( 'INSERT INTO users (name, age) VALUES ($1, $2)', ['Ada', 36],);Go:
rows, err := db.SQL(ctx, "SELECT DISTINCT team FROM users WHERE age >= $1 ORDER BY team", 18,)plan, err := db.ExplainSQL(ctx, "SELECT * FROM users WHERE age >= $1", 18)inserted, err := db.SQL(ctx, "INSERT INTO users (name, age) VALUES ($1, $2)", "Ada", 36,)Vector search
Section titled “Vector search”All four clients expose exact vector search. Embeddings are computed outside
NonoDB, by the application or a local embedding service. The indexed field must
be a JSON array of exactly dims finite numbers; one vector per document per
indexed field is supported. Vectors are maintained in the same transaction as
document writes.
Python:
articles.create_vector_index("embedding", 384, metric="cosine")articles.insert({"title": "Async Rust", "embedding": embed("Async Rust")})
hits = articles.vector_search( "embedding", embed("rust async"), filter={"published": True}, skip=0, limit=10,)for hit in hits: print(hit["_distance"], hit["title"])
print(articles.list_vector_indexes())articles.drop_vector_index("embedding")Rust:
use serde_json::json;
let embedding = vec![0.12_f32, -0.03, 0.44];articles.create_vector_index("embedding", 3, "cosine")?;articles.insert(&json!({ "title": "Async Rust", "embedding": embedding.clone(),}))?;
let hits = articles.vector_search( "embedding", &embedding, Some(&json!({"published": true})), 0, // skip 10, // limit)?;for hit in &hits { println!("{} {}", hit["_distance"], hit["title"]);}
let indexes = articles.list_vector_indexes()?;articles.drop_vector_index("embedding")?;Node.js:
const queryVector = [0.12, -0.03, 0.44];
await articles.createVectorIndex('embedding', 3, 'cosine');await articles.insert({ title: 'Async Rust', embedding: queryVector });
const hits = await articles.vectorSearch('embedding', queryVector, { filter: { published: true }, skip: 0, limit: 10,});for (const hit of hits) { console.log(hit._distance, hit.title);}
const indexes = await articles.listVectorIndexes();await articles.dropVectorIndex('embedding');Go:
queryVector := []float32{0.12, -0.03, 0.44}
_, err := articles.CreateVectorIndex(ctx, "embedding", 3, "cosine")_, err = articles.Insert(ctx, map[string]any{ "title": "Async Rust", "embedding": queryVector,})
hits, err := articles.VectorSearch(ctx, "embedding", queryVector, nonodb.VectorOptions{ Filter: map[string]any{"published": true}, Skip: 0, Limit: 10,})for _, hit := range hits { fmt.Println(hit["_distance"], hit["title"])}
indexes, err := articles.ListVectorIndexes(ctx)_, err = articles.DropVectorIndex(ctx, "embedding")Behavior common to all clients:
metriciscosine(default),dot, orl2._distanceis lower-is-better:1 - cosine_similarity, negative dot product, or squared Euclidean distance.- Search is exact and scans the whole vector index, so unfiltered cost is
O(N × dims). There is no ANN/recall loss. - Missing, malformed, or wrong-length vectors are skipped; writes still succeed.
- Creating an index backfills existing documents synchronously. Auto-index does not create vector indexes.
- Exact
_idand indexed filters use a document-first path. A highly selective filter on an unindexed field can approach a full collection scan. - Use the same embedding model, dimensions, and metric for stored vectors and queries. Changing the model requires re-embedding documents and rebuilding the index.
See HTTP API: vector indexes and HTTP API: vector_search for the raw protocol.
Vault collections
Section titled “Vault collections”Vault collections require the three encryption headers on every request. Each client has a credential-bound handle that adds them automatically.
Python:
vault = db.vault("acme", "acme:v1", os.environ["ACME_VAULT_KEY"])docs = vault.collection("vault")Rust:
let vault = db.vault("acme", "acme:v1", std::env::var("ACME_VAULT_KEY")?);let docs = vault.collection("vault");Node.js:
const vault = db.vault('acme', 'acme:v1', process.env.ACME_VAULT_KEY);const docs = vault.collection('vault');Go:
vault := client.Vault("acme", "acme:v1", os.Getenv("ACME_VAULT_KEY"))docs := vault.Collection("vault")All four handles use the normal CRUD methods. In a vault collection, only
_id/tenant_id filters and single-document update/delete are valid. batch,
write_batch, search, fuzzy, aggregation, and indexes are rejected by the
daemon. See Vault collections.
API coverage
Section titled “API coverage”All clients expose the common document operations:
create_collectionfor explicit standard/vault collection creation, with an optional default TTL (create_collection_with_ttlin Rust, an optional argument in Python/Node.js,CreateCollectionWithTTLin Go);set_collection_ttl/get_collection_ttlfor collection TTL defaults and optional history purging on expiry;insert,insert_many,find,find_one,update,delete,count;aggregatefor reporting pipelines, plus transactional$out/$mergewrite stages;batch(read-only) andwrite_batch(atomic writes);lookup/lookup_onefor ordered point lookups by_idor a unique index, plusget_manyfor fetching documents by_id;watch/watch_oncefor append-only outbox events, with filters, projections, resume tokens, and reconnect helpers; Python also exposeswatch_streamfor continuous NDJSON (details);historyandget_versionfor document revisions (per-collection history enabled);- single-field, compound, unique, and covering indexes;
- full-text (
search), fuzzy search, and exact vector search; - text/fuzzy/vector index listing and deletion;
- collection listing and health checks;
- LMDB map information/growth in Python and Rust (or raw
execelsewhere); - vault collection handles in Python, Rust, Node.js, and Go.
Use exec/Exec/exec for an operation that does not have a typed wrapper.