Roadmap and limits
nonodb is intentionally narrow. This page lists what is supported today, what is deliberately out of scope, and which gaps are candidates for future work.
Current status
Section titled “Current status”The project is at 0.26.0. It is suitable for local, single-host, and
primary/replica deployments that need a small, durable, queryable JSON store
and can accept a single-writer model per database.
Implemented:
- JSON documents and collections; automatic UUID
_idon the HTTP/core path and driver-generated ObjectId_idon the MongoDB wire path; - MongoDB-style filters, projections, sorts,
skip/limit; - SQL
SELECT,INSERT,UPDATE, andDELETEover one collection;SELECTsupportsDISTINCT,WHERE,GROUP BY,HAVING, aggregates includingCOUNT(DISTINCT field),CASE, scalar functions,ORDER BY,LIMIT/OFFSET, positional parameters, andexplain_sql; simple field-only queries use the normal indexedfindpath, while writes use the single writer and are atomic per statement, includingUPDATE SETexpressions; - CRUD, multi-update, replacement updates, pipeline updates, upserts;
$set,$unset,$inc,$mul,$min,$max,$rename,$currentDate,$bit,$pop,$push,$pull,$pullAll,$addToSet,$setOnInsert,$each,$position,$slice,$sort;- array updates with positional
$,$[],$[identifier], andarrayFilters; - atomic find-and-modify returning the old or new document;
explainwith access path, index/bounds, sort coverage, and actual counts;comment,maxTimeMS, index hints, and$naturalsort for find queries and cursors;maxTimeMSalso boundscountand aggregation scans;- single-field, compound, unique, and covering indexes;
- single-field GeoJSON point geo indexes with
$near,$geoWithin, and$geoIntersects; - index-only sorted scans and index-backed counts;
- BM25 full-text search with diacritic folding and phrases;
- fuzzy search with trigrams and bounded Levenshtein distance;
- exact brute-force vector search with cosine, dot, and L2 metrics;
- read batches and atomic write batches;
- ordered point lookups by
_idor a unique single-field or compound index, with covering projections,_idexclusion, key deduplication, and a response size cap; - durable background jobs through an ordinary
_jobscollection and external workers, with leases, retries, and idempotent enqueue; - outbox events through an ordinary
_eventscollection, with atomic data + event writes, automatic per-collection insert/update/delete events, optional field-change filtering, sortable event ids, per-consumer checkpoints, and server-sidewatchlong-polling and continuous NDJSON/SSE streaming; - server-side stream filtering by topic and payload, plus count thresholds with grouping and time windows;
- persistent conditional subscriptions with document filters, index-backed
count conditions, level-triggered delivery by default, and optional
edge-triggered (
once) mode; - connection-scoped live subscriptions (
watchwithmode:"live") that push matching changes directly to SSE/NDJSON without writing to_events; - an embedded local web console (
nonodb-cli gui) with document CRUD, collection settings, indexes, SQL, map settings, per-collection metrics, and authorization management; - per-collection append-only document revision history with retention (
0disables); - document TTL with collection defaults, per-document overrides, and background expiry;
- BSON-compatible dates with RFC 3339 input, UTC normalization, indexed ranges, and sorting;
- Unix-socket daemon, optional TCP/TLS and mutual TLS, file-based principals and scopes, uid/gid allow-lists;
- group commit, request limits/timeouts, JSON and Prometheus metrics, health/readiness, disk and snapshot monitoring;
- snapshots, online backup, SHA-256 manifests, deep verification, restore drills, CLI;
- GUI backup jobs with full/restic engines, multi-database selection, exclusions,
gzip compression, age/restic encryption, local/S3/R2 destinations, and
backup-info.txt; - admin-only staged import from local folders or S3/R2 into a new database;
- optional vault collections with per-tenant whole-document encryption;
- asynchronous primary/replica replication over HTTP/TLS with durable ordered operations, snapshot bootstrap, metadata/index/history/events/subscriptions, replica acks, retention, quorum promotion, leases, automatic election, in-place hard resync, pause/resume/disconnect, write routing, and a cluster-wide GUI;
- configurable parallel index backfill and automatic index builds;
- optional Network GUI/API with a dedicated nftables table, advertised replica URL discovery, and a per-user daemon instance registry;
- Python, Rust, Node.js, and Go clients, Docker image, systemd unit;
- unit, property, integration, concurrency, crash, search, and large-data tests.
Deliberate limitations
Section titled “Deliberate limitations”Transactions and concurrency
Section titled “Transactions and concurrency”- No general interactive transactions. There is no
begin/commitAPI spanning multiple requests. write_batchis the atomic primitive. It is all-or-nothing, but it is a single request and cannot read intermediate results from outside.- No cross-request read-modify-write isolation. Two requests can interleave.
Use
find_and_modify, atomic update operators ($inc), orwrite_batch. - One writer. All writes are serialized. This is a design choice, not a temporary limitation.
- Replication is asynchronous and primary/replica, not multi-writer. Sharding and cross-database transactions are not implemented. The control plane replicates auth, backup jobs/state, the database catalog, and the cluster peer token; encrypted vault envelopes also replicate. Backup artifacts, TLS private keys, mode files, node-local settings, and audit logs do not. See the replication and cluster guide.
Query language
Section titled “Query language”See MongoDB compatibility for a feature-by-feature comparison and practical migration caveats.
- The aggregation pipeline is bounded by
NONODB_AGGREGATE_MAX_DOCS(default 100,000 intermediate documents). It supports equality$lookupjoins,$lookupletvariables, nested lookups,$unionWith,$graphLookup,$setWindowFieldswith document/range frames and advanced analytics,$densify,$fill,$out,$mergewithletandwhenMatchedpipelines,$facet,$bucket, and$bucketAuto. Group state is held in memory; there is no disk spill. - No
$wherequery operator. The HTTP/core query language has no$text; MongoDB wire$textis a documented lexical subset backed by MongoDB-style text indexes. $jsonSchemasupports the common validation keywords but not every JSON Schema draft feature.$expruses the aggregation expression evaluator, including variables, common comparison, array, string, conditional, and date operators, including$dateDiffand custom$dateFromStringformats. Date time zones support UTC and fixed offsets, not IANA identifiers. Expression errors do not match the document instead of aborting the query.- Projection supports nested paths, positional
$,$slice,$elemMatch, and basic$meta. Native search supplies_score, HTTP$meta: "textScore"maps it, and MongoDB wire$textcomputestextScorewith BM25. $regexsupportsi,m,s,x, anduoptions, but not MongoDB’s PCRE-only constructs; patterns use Rust’s non-backtracking regex engine.$in,$nin,$all, and$elemMatchaccept{"$regex": ...}operands, but stored BSON regex values are not implemented. Multikey indexes serve array equality,$all, ranges, and simple$elemMatch;$sizeis not index-backed.- No joins.
lookupis a point/batch lookup, not a general join, and requires a matching unique index for non-_idkeys. Non-unique lookups are not supported. - SQL covers one collection. Joins, subqueries, scalar expressions in grouped
SELECT,RETURNING,INSERT ... SELECT, andUPDATE ... FROMare not supported yet. AggregateDISTINCTis limited toCOUNT(DISTINCT field). - No stored procedures or daemon plugins. Background jobs and outbox events are
ordinary client processes.
watchlong-polls or streams append-only outbox collections; it is not an automatic change stream for arbitrary writes, updates, or deletes. - TTL is eventual and has no strict read-time filtering.
- Projection expressions are limited; nested paths, positional
$, and basic$metaare supported, but arbitrary computed projection expressions are not. - Sorting and filtering use the documented subset; there is no collation API.
- Dates are instants only. IANA timezone names and timezone-aware aggregation
expressions are not implemented; clients must send RFC 3339 with
Z/offset. - Existing ISO 8601 strings are not migrated to dates automatically.
- Decimal128 support includes finite values and
NaN/Infinity. Arithmetic results round to 34 significant digits; values outside the Decimal128 exponent range returninvalid_numeric. - Long text has no dedicated type; the 1 MiB document limit applies to strings.
- ObjectId is supported as both a field value and
_id. - BSON regular-expression values and legacy code/symbol types are not implemented.
Updates
Section titled “Updates”- Pipeline updates support
$set,$addFields,$unset,$project,$replaceRoot, and$replaceWith. _idis immutable by contract; changing it with update operators is not supported.
Indexes
Section titled “Indexes”- Scalar values and array elements are indexed. Numbers use exact decimal keys shared by integers, floats and Decimal128; dates use the Extended JSON date type; binary/UUID and ObjectId use dedicated type tags. A compound index may contain at most one array field; parallel arrays are rejected. Ordinary objects are skipped. Indexes created before format 5 must be recreated to include array entries.
- No sparse/partial indexes, wildcard indexes, or text indexes with custom analyzers. Geo indexes currently cover single-field GeoJSON points; polygon/line document indexes are not implemented.
- Vector indexes store one vector per document and scan the whole index for each query. There is no ANN (HNSW/IVF/PQ), multi-vector document index, or built-in embedding model; clients send ready vectors. Auto-index does not create vector indexes automatically.
- Filtered vector search uses an exact
_idor a secondary index when one is available. A highly selective filter on an unindexed field may require a full document scan. - No index intersection or cost-based optimizer. The planner uses a simple prefix/range rule.
- A covering projection requires an explicit
includelist and an inclusive projection. drop_*reuses index/search sub-database slots. Legacy databases created by older releases remain registered until a compacting restore.MAX_DBS=1024; collection count plus concurrent index/search resources must stay below that limit.
Search
Section titled “Search”- No stemming, stop-word removal, synonyms, thesaurus, or per-language analyzers.
- BM25 terms are ORed; there is no
AND/ORquery parser beyond quoted phrases. - Phrases require contiguous tokens; no slop parameter.
- Fuzzy search caps candidate evaluation at 5,000 documents and supports only bounded Levenshtein distance.
- Search indexes cover scalar values only.
- Reindexing is required after analyzer changes.
Protocol and clients
Section titled “Protocol and clients”- The optional MongoDB-compatible wire listener implements a documented subset
for official drivers: handshake, CRUD, cursors, count, distinct, aggregate,
index DDL, collection DDL, MongoDB-style text indexes and
$text, SCRAM-SHA-256/SCRAM-SHA-1 authentication, authSource validation, auth-file principal scopes, aggregate cursor batching, strict rejection of unsupported driver options, mongoexport/mongodump-compatible export, PyMongo/Node.js/Go conformance, and TLS. It does not support client-certificate authentication, sessions, multi-document transactions, change streams, collation, or full MongoDB feature parity. - The supported API is HTTP/JSON; no gRPC, binary framing, or CBOR API.
- The Python client is a single module, not a published package.
- The CLI covers common administration, not every possible operation.
Security
Section titled “Security”- No built-in user directory, role hierarchy, or credential expiry policy; principals and per-collection scopes live in a daemon-managed file.
- Audit logging is append-only JSONL to a local file; there is no remote log shipping or tamper-evident chain.
- Failed-login lockout is process-local and keyed by the TCP peer IP. It does not trust proxy headers, share state between daemons, or distinguish users behind one NAT address.
- Vault encryption is daemon-side, not end-to-end. The daemon sees plaintext and the raw key in memory.
- Vault collections have no searchable encryption, blind indexes, range
queries, or sorting beyond
_id. - Vault key rotation is an operational re-encryption procedure; the daemon does not keep a keyring of old keys.
- Mutual TLS is supported, but revocation uses the auth registry; there is no CRL or OCSP integration.
- Client certificates map to a principal with collection scopes, not to a separate user or tenant hierarchy.
- Unix peer checks use uid and primary gid only, not supplementary groups.
- TCP requires
NONODB_AUTH_FILEbut is plaintext unless TLS is configured.
Storage and operations
Section titled “Storage and operations”- LMDB file size does not shrink after deletes. Use a compacting backup and restore to reclaim space.
map_sizecan grow online; shrinking the reservation requires a restart and the file itself only shrinks through a compacting backup/restore.- No write-ahead log or point-in-time recovery. Snapshots and native backups are periodic full consistent copies; deduplicated incremental repositories use the restic engine.
- No online schema migration framework.
- No native compression at rest; restic repositories compress their own data.
- No storage encryption; use filesystem/volume encryption if needed.
- No multi-tenant isolation inside one database.
- No built-in TLS certificate rotation or secret management.
Known trade-offs
Section titled “Known trade-offs”| Decision | Consequence |
|---|---|
| LMDB + copy-on-write | Excellent crash safety and read concurrency; file never shrinks |
| One writer + group commit | Predictable durability and good fsync amortization; writes serialize |
| One daemon owns the file | Safe preforking; one more process to supervise |
| JSON on disk | Human-readable and flexible; larger/slower than CBOR for large data |
| Simple optimizer | Predictable; misses some multi-index opportunities |
| Global token auth | Simple; insufficient for multi-tenant roles |
| Snapshot-based backup | Simple; not PITR |
| Projection tree model | Nested paths, positional $, $slice, $elemMatch, and basic $meta work |
Candidate future work
Section titled “Candidate future work”These are not commitments. They are ordered roughly by expected value for the project’s target workload.
GUI and operator experience
Section titled “GUI and operator experience”- Database management from the GUI. Create/drop databases, not just select them.
- Backup verification and restore APIs. Let the GUI verify manifests and show restore instructions without direct filesystem access.
- Multiple daemon tabs. Keep several profiles connected simultaneously.
- Import progress and large result sets. Cancellable/resumable imports and virtualized large result sets.
- Accessibility and theming. Keyboard navigation, screen-reader labels, and an optional light theme.
High value
Section titled “High value”- Raw JSON passthrough for simple reads. For
findwithout projection or sorting, stream stored JSON bytes directly into the response instead of parsing toValueand reserializing. Expected read-path win. - Incremental index backfill writes (implemented). Backfill streams chunks capped by document count and raw bytes, applies entries as each chunk completes, and avoids collection-sized unique-key maps.
- Reindex tooling (implemented). The
reindexoperation and CLI/GUI/Python entry points rebuild secondary, text, fuzzy, and vector indexes in one write transaction. - Operational hardening. More metrics such as latency histograms and per-stage query timings. Health/readiness, index-build status, structured logs, and graceful drain are implemented.
Medium value
Section titled “Medium value”- Role hierarchy and inherited groups. Principal tokens, database-qualified scopes, and mTLS-to-principal mapping already exist.
- Point-in-time recovery / WAL for stricter durability and recovery objectives.
- Stop words, stemming, and per-index analyzers; possibly an integration with Tantivy for advanced text search.
- Timezone-aware date expressions for aggregation, including IANA timezone identifiers for local calendar operations.
- Non-finite Decimal128 values and decimal comparison across all numeric edge cases, building on the current finite Decimal128 support.
- BSON regex values, plus matching
$typeentries and global sentinel range behavior. - Compression and/or CBOR storage for smaller files and faster parsing, with a migration path.
- Expanded aggregation beyond the current
$match/$group/$bucket/$bucketAuto/$project/$sort/$limit/$facet/$sample/$lookup/$unionWith/$graphLookup/$setWindowFields/$densify/$fill/$out/$mergesubset, including streaming execution.
Lower priority
Section titled “Lower priority”- Sparse/partial and wildcard indexes.
- Approximate vector indexes (HNSW/IVF/PQ) and polygon/line document geo indexes.
- Published package-registry releases for the existing Python, Rust, Node.js, and Go clients.
- Benchmark automation in CI.
- Shared or hosted web administration beyond the embedded local GUI.
Non-goals
Section titled “Non-goals”- Full MongoDB feature parity. The documented MongoDB-compatible subset targets common driver workloads and deliberately excludes sessions, multi-document transactions, change streams, collation, and other advanced MongoDB features.
- Distributed consensus, multi-writer clusters, or sharding. Asynchronous primary/replica replication is supported; see the replication and cluster guide.
- A general-purpose OLAP engine.
- Full MongoDB feature parity.
- Running multiple writers against one LMDB environment.
- Cross-database queries or transactions.
- Network filesystems for the instance root.
Versioning
Section titled “Versioning”Before 1.0, the HTTP API and on-disk format may change. Changes that affect data compatibility should be accompanied by migration or reindex instructions. Backups should be taken before upgrades.
Contributing
Section titled “Contributing”See Development for build/test instructions and contribution guidelines.