For AI agents: read this first
ndb is one Go daemon. It stores documents (JSON objects) in collections and answers HTTP/JSON over a unix socket or TCP. Every SDK (Go, Ruby, Rails, TypeScript) and the CLI are thin layers over the same HTTP API: when an SDK and the HTTP docs differ, the HTTP docs are the contract.
Run and connect
ndb servewith no flags (not as root): data in~/.ndb/data, unix socket~/.ndb/ndb.sock, TCP127.0.0.1:7070. As root, or with/var/lib/ndb: socket/run/ndb/ndb.sock, no TCP.- The SDKs read
NDB_URL(unix:///path/ndb.sock,http://host:port). Over TCP with a token:Authorization: Bearer <token>. The unix socket needs no token. GET /_healthis{"status":"ok"}when ready;503 not_readywhile it recovers. The SDKs retry that for 10 s.- Logs:
ndb serve -log-level debug|info|warn|error|quiet, orPUT /_log {"level":"debug"}with an admin token.
Rules that agents get wrong
- Collection names match
^[a-z0-9][a-z0-9_-]{0,63}$. A path segment that starts with_is the daemon, never a collection. _idis the primary key, a non-empty string; ndb makes a UUIDv7 when it is missing. An existing_idon insert is409 duplicate_id._vis the version, set by the daemon and added to every answer. A_vthat you send in a document is dropped. To write only on a given version, use the guard:POST /{coll}/_update/{id}with{"query":{"_v":3},"update":{...}}(no match ={"matched":0}). The SDKs wrap it inwith_retry(WithRetry,withRetry): read, change in a function, write with the guard, and retry on a conflict (stale_objectafter 5 tries); the function can run more than once.$unwindin_aggregate, before$group:{"$unwind": "$items"}makes one row per array element (MongoDB rules; optionspreserveNullAndEmptyArrays,includeArrayIndex). One per pipeline; a$matchafter it filters the elements.- Encrypted fields:
PUT /users {"encrypted":["cpf"]}: the daemon stores"ndb:e1:k1:..."(AES-256-GCM), never the plain value, also in logs. Answers have the sealed string by default; a read with?decrypt=1by the unix socket, the full token or a token withdecrypt: [users]gets the plain value (without the right, the sealed string; no error). SDKs senddecrypt=1;Encrypted()/encrypted()/.encryptedsenddecrypt=0. Only$set/$unsetchange the field; a filter on it is only$exists. Add"blind":{"cpf":"numeric"}(orexact,lower,upper; or a list of exact fields; a blind field is encrypted too) to find it:$eq,$in,$ne,$nin,indexes,uniqueand$groupby"$cpf"then work on a hidden hash fieldcpf_bidx; no range, regex or sort. A field added toencryptedorblindlater encrypts the old documents in the background ("encrypting"inGET /{coll},buildingthenready); until then a filter also finds the old plain values. Key rotation:ndb key rotate(or-envforNDB_ENCRYPTION_KEY, withNDB_ENCRYPTION_KEY_OLDat the next start), on the host only;POST /_cluster/keyis unix socket only, no SDK. A lost key cannot be rotated. - Settings:
GETandPUT /_cluster/settings(admin): the log settings, stored in the data dir ({"log":{"level":"debug"}}), and the encryption key, masked. The key comes fromNDB_ENCRYPTION_KEY(64 hex), or is made at the first start and kept in the data dir and the backups. - Indexes:
indexes: ["status", "account_id,created_at"]. A name with commas is a compound index (2 to 4 fields): it serves equality on the first fields, then a range on the next one; it does not order the rows.unique: ["account_id,email"]is a compound unique key.X-Ndb-Plannames the index used. - Optimistic locking (the default):
_vneeds no setup. Rails models guard every save with it (Ndb::StaleObjectError); in Go, TypeScript and Ruby pass it as a guard or usewith_retry. Overview of optimistic locking, pessimistic locking and transactions:docs/dev/concurrency.md. - Pessimistic locking (one holder):
POST /{coll}/_lock/{id}{"ttl":"30s","wait":"10s"}answers{"token","expires_at","doc"}. Write with?lock=<token>, thenPOST /{coll}/_unlock/{id}{"token"}. Other writes of the document wait; another_lockwaits, then423 locked; a stale token is409 lock_expired. SDKs:lock(id) { }(Lock,lock), RailsModel.lock.find(id) { }. Use it when the code has an effect outside ndb. - Transaction (one collection):
POST /{coll}/_lock{"ids":[...],"ttl":"5s"}locks a set (all or none, one token, no deadlock).POST /{coll}/_tx{"ops":[{"op":"insert","doc":{}},{"op":"update","id","update","query"},{"op":"delete","id"}],"locks":[token],"unlock":true}writes all ops in one WAL record or none; an update or delete that matches nothing is409 tx_conflict; an expired lock is409 lock_expired.POST /{coll}/_unlock{"token"}releases a set. No transaction across collections: write the side effects first with fixed ids and the status last, or use an outbox (docs/dev/concurrency.md#writes-across-collections). SDKs: RailsModel.transaction(lock: [a, b], ttl: 5) { ... }(writes collected,Ndb::Rollback), Gocoll.Tx(ctx, ids, fn)(ndb.ErrRollback), TScoll.transaction(ids, fn)(Rollback), Rubycoll.transaction(lock: ids) { |tx, docs| }. - Field names that start with
$are refused (invalid_field), except$blob(a blob reference). Names that start with_are reserved. - Writes go through
updateoperators:$set,$unset,$inc,$push,$pull,$min,$max,$setOnInsert. Integers stay exact (an int64 overflow isinvalid_field). - Queries are JSON in the body key
query, with MongoDB-like filters ($eq,$in,$gte,$regex,$elemMatch,$and,$or,$not).fieldskeeps only the listed paths (_idtoo only if you list it)._idis the last tie-break of a sort, in the direction of the last sort key. An RFC 3339 string (2026-11-12T15:00:05Z) is an instant on every field (any width or offset;_idstays text). Write times in UTC with milliseconds, as the SDKs do (Go:time.Timefields andndb.Time). - Unknown body keys are errors (
invalid_request,invalid_query,invalid_pipeline): a typo never passes silently. - Only
_docand_bulkcreate a collection._update/{id}(also with upsert),_expireand_persiston an unknown collection are404 unknown_collection:PUT /{coll}first. _bulkis all or nothing, also on a partitioned collection (all checks run before any write).- Partitioned collections (
partition_by, set only when the collection is made):_idis unique across the partitions, and a partition name (calls-2026-11) belongs to its logical collection. - Patterns (
logs-*,a,b) work only onGET /{coll},_search,_count,_aggregate. Every other route ispattern_read_only. - Drop and truncate need
?confirm={coll}.
Streams (Redis Streams model, on disk)
- A stream is a collection made with
"stream": true(or by its first append). Routes are under/{s}/_streams/.... - Entries are append only:
POST _doc,_bulk,_update*,_delete_by_query,_expire,_persiston a stream are400 stream_append_only. Delete one entry withDELETE /{s}/_doc/{id}, or trim. - An entry ID is
<ms>-<seq>. Read with a group (groups/{g}/read, thenack), without a group (_streams/read, XREAD), or with_search. - Delivery is at least once: make the work safe to repeat. A pending read counts as a delivery, as in Redis.
- Delayed retry is ndb only:
nackwithdelay_ms, thenclaim {"due": true}. The SDK workers do it with a retry schedule (Retry/retry:/retry) and a max age; a poison entry goes to<stream>_dead, and nothing sends it back by itself. - The Redis commands exist in each SDK for a move from Redis: Ruby
Ndb::Client#xaddand the others, Gosdk/go/ndbredis, TypeScript@thadeu/ndb/ioredisand@thadeu/ndb/node-redis.
Pick the SDK page
- Rails app:
ndb-rails. Models withNdb::Record(wherefor a list,find_byfor one,find(id)by id,to_ndbgives the JSON body). Each model hascreated_atandupdated_atwith an index, andscope,uniqueness:,dependent:andreadonly?work as in ActiveRecord. Streams withinclude Ndb::Streamsinapp/streams, run withbundle exec ndb streams, test withNdb::Streams.inline!orperform_now. - Plain Ruby: the gem
ndb(Ndb::Client). - Go:
github.com/thadeu/ndb/sdk/go(standard library only). - TypeScript (Node, Bun, Hono):
@thadeu/ndb.
Errors
Every error has the body {"error":{"code","message"}}. The SDKs turn each code into a typed error (Go ndb.ErrUnknownCollection, Ruby Ndb::UnknownCollection, TypeScript UnknownCollectionError). The full list is on the Errors page.