Repository navigation
Releases
v0.26.0 - MongoDB-compatible subset and unified text search
v0.26.0 - MongoDB-compatible subset and unified text search
NonoDB 0.26.0 adds a documented MongoDB-compatible wire subset for official
drivers, MongoDB-style text indexes with $text, a unified search-index
definition, and a broad set of query, aggregation, indexing, and operational
hardening changes.
This release targets applications that use ordinary MongoDB driver CRUD,
cursors, indexes, and basic aggregation. It is not full MongoDB parity:
sessions, multi-document transactions, change streams, collation, $where,
MongoDB $search/Atlas Search, full mongosh, Compass, and BI connectors
remain out of scope. Unsupported commands and options fail loudly instead of
being silently ignored.
Highlights
- MongoDB-compatible wire endpoint for PyMongo, Node.js, and Go drivers:
handshake, CRUD, cursors, count, distinct, aggregation, index and collection
DDL,dropDatabase, SCRAM-SHA-256/SHA-1, TLS, andauthSourcevalidation. - MongoDB-style text indexes and
$textwith multi-field weighted BM25,
positive terms and phrases, negative clauses,$meta: "textScore", and text
index DDL throughcreateIndexes/listIndexes/dropIndexes. - Unified search-index definitions shared by native text search, native
fuzzy search, and MongoDB$text, with weighted multi-field definitions and
replication support. - BSON compatibility improvements: ObjectId
_idfor driver-created
documents and wire upserts, Timestamp/MinKey/MaxKey, non-finite Decimal128,
and BSON regex values as read predicates. - Direction-aware indexes: MongoDB-style index names and key directions,
mixed ascending/descending compound indexes, sorted queries, and unique
lookups. - Wire correctness and safety: aggregate cursor batching and
getMore,
strict rejection of unsupported driver options, read/write concern validation,
list filter support, principal-scoped authorization, connection limits, and
handshake/read/write timeouts. - MongoDB tooling and conformance:
mongoexport,mongodump,bsondump,
mongoimport, andmongorestore --nsFrom/--nsTochecks; conformance tests
against a real MongoDB server; Node.js and Go driver tests; and a static
MongoDB portability checker. - Query and aggregation compatibility expanded with pipeline updates,
$lookupvariables and nested lookups,unionWith,graphLookup,
setWindowFields,densify,fill, date expressions, index hints,
comment,maxTimeMS, and nested positional/meta projections. - Operational hardening: request latency histograms, online resize and
crash recovery coverage, a 10M-document campaign, and MongoDB wire connection
limits/timeouts.
Breaking changes and upgrade notes
- Search-index metadata changed. Text and fuzzy index definitions are now
stored as unifiedSearchIndexDefrecords. Oldtext:/fuzzy:definition
keys are not migrated automatically.- Drop and recreate native text/fuzzy indexes after upgrading.
- MongoDB-style text indexes should be recreated as well if the data directory
came from an older development build. reindexnow preserves full multi-field definitions, including field
weights, and is the preferred rebuild path for existing unified indexes.
- MongoDB wire writes without an explicit
_iduse ObjectId; the HTTP/core
path keeps UUID v4 defaults. - Stored BSON regex values remain unsupported. Driver regex literals are
accepted as read filters; writes that try to store a regex value fail with
BadValue(code 2). - MongoDB wire support remains an optional listener controlled by
NONODB_MONGO_ADDR; the HTTP/JSON API remains the native interface.
MongoDB compatibility notes
- One global SCRAM credential and one listener-level principal scope per wire
listener; there is no MongoDB user database, per-database users/roles, X.509
username mapping, or replica-set URI support. - Vault headers (
X-NonoDB-Tenant,X-NonoDB-Key-Id,X-NonoDB-Key) cannot be
carried by a MongoDB driver. Use the native client/HTTP API for vault
collections; a plaintenant_idfield is indexed data, not encryption. $textis a deliberately lexical BM25 subset: no stemming, no stop words, and
onlydefault_languageabsent or"none". It is supported infind,
count,distinct, and a leading aggregate$match;maxTimeMSwith
$textis rejected.- BM25 remains expensive for very frequent terms over a large text index. A
10M-document / 1M-text-document run measured a frequent-term p50 of about
9.2 s. Optimization of large postings is tracked as a follow-up. - Java is not in the automated driver matrix. PyMongo, Node.js, and Go are.
Configuration
MongoDB wire settings are opt-in. Relevant variables include:
NONODB_MONGO_ADDR,NONODB_MONGO_USERNAME,NONODB_MONGO_PASSWORDNONODB_MONGO_AUTH_MECHANISM,NONODB_MONGO_AUTH_SOURCE,
NONODB_MONGO_PRINCIPALNONODB_MONGO_TLS_CERT,NONODB_MONGO_TLS_KEYNONODB_MONGO_MAX_CONNECTIONSNONODB_MONGO_READ_TIMEOUT_SECS,NONODB_MONGO_WRITE_TIMEOUT_SECS,
NONODB_MONGO_HANDSHAKE_TIMEOUT_SECS
See docs/operations.md and docs/mongodb-compatibility.md for the full
contract and defaults.
Validation performed
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace- MongoDB wire conformance against a real MongoDB 8.x server
- Official PyMongo, Node.js, and Go driver checks
mongoexport/mongodump/mongoimport/mongorestoreportability checks- MongoDB wire auth, connection-limit, and timeout tests
- Native search, fuzzy, vector, replication, backup, restore, durability,
crash-recovery, multi-database, GUI, and security suites - 10M-document load/query/index campaign and a 10M-document crash test
- Release build with
--lockedin GitHub Actions
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6afb7249991a96d9890b5de0 - Workflow run:
43957910184 - Commit:
1c02981 - Findings: 0 critical, 0 high, 0 medium, 9 low, 5 info (402 tests)
- Report artifact:
liveapisec-report
Assets
nonodb-v0.26.0-linux-x86_64.tar.gznonodb-v0.26.0-macos-x86_64.tar.gznonodb-v0.26.0-macos-arm64.tar.gznonodb-v0.26.0-windows-x86_64.zip- Matching
.sha256checksum files for each archive - GHCR images:
ghcr.io/essmos/nonodb:0.26.0,
ghcr.io/essmos/nonodb:0.26, andghcr.io/essmos/nonodb:latest
Full changelog: v0.25.0...v0.26.0
v0.25.0 - Replication controls, automatic discovery, and driver write routing
v0.25.0 - Replication controls, automatic discovery, and driver write routing
NonoDB 0.25.0 rolls up the 0.25.0-rc.1, rc.2, and rc.3 pre-releases and
adds opt-in write routing to every official driver. The main theme is operating
a primary/replica cluster in practice: create a replica with a one-time pairing
code, let it advertise itself automatically, control it from the CLI or GUI, and
route writes to the current primary without turning reads into remote calls.
Quick start: one code on the primary, Docker on the client
On the primary, generate a pairing code with the CLI:
nonodb-cli replication add-replica replica-docker default
# Pairing code: K7M4P9QX
# On the replica, run:
# nonodb-cli replication join http://10.0.0.10:7878 K7M4P9QXOn the client, start a Docker replica. The only required local settings are the
empty data volume, auth file, replica role, and a reachable advertised URL. Do
not set source or source-token variables; replication join installs them from
the primary.
# Prepare the replica auth file once.
docker run --rm \
-v nonodb-replica-data:/var/lib/nonodb \
-e NONODB_AUTH_FILE=/var/lib/nonodb/auth.json \
ghcr.io/essmos/nonodb:0.25.0 \
nonodb-cli auth init
# Start the read-only replica API on host port 7912.
docker run -d --name nonodb-replica \
-p 7912:7878 \
-v nonodb-replica-data:/var/lib/nonodb \
-v nonodb-replica-run:/run/nonodb \
-e NONODB_AUTH_FILE=/var/lib/nonodb/auth.json \
-e NONODB_TCP=0.0.0.0:7878 \
-e NONODB_REPLICATION_ROLE=replica \
-e NONODB_REPLICATION_NODE_ID=replica-docker \
-e NONODB_REPLICATION_ADVERTISE_URL=http://10.0.0.3:7912 \
ghcr.io/essmos/nonodb:0.25.0
# Redeem the pairing code through the local daemon socket.
docker exec nonodb-replica nonodb-cli replication join \
http://10.0.0.10:7878 K7M4P9QX
docker exec nonodb-replica nonodb-cli replication statusAfter the first acknowledgement the primary GUI discovers the replica at
http://10.0.0.3:7912 and shows its role, lag, and metrics. Behind Docker, NAT,
a reverse proxy, or TLS termination, keep setting
NONODB_REPLICATION_ADVERTISE_URL explicitly; never advertise the container
172.x address.
NonoDB still has a single writer and no sharding. A cluster is one
primary plus read replicas and optional hot standbys, with quorum failover. It
is not a multi-primary or sharded database. See
Replication and cluster guide.
Highlights
Pairing-first replica onboarding
- The supported way to add a replica is now a one-time, 8-character pairing code
created on the primary:- GUI → Replication → Add replica;
nonodb-cli replication add-replica <name> [databases];- alias
nonodb-cli replication pair; nonodb-cli replication join <primary-url> <code>on the replica.
replication joinnow installs the source URL, source token, database list,
poll interval, batch size, and bootstrap mode from the primary. Operators no
longer need to copyNONODB_REPLICATION_SOURCE,
NONODB_REPLICATION_SOURCE_TOKEN, orNONODB_REPLICATION_DATABASESinto a
paired replica.- Joining demotes a writable node to a read-only replica, stores the returned
source and token in the hidden.nodestate, and applies the replicated auth
registry, backup configuration, and database catalog. - The join command prints the node id, source, selected databases, role, and
first pull result, and waits briefly so configuration errors are visible
immediately. - Pairing codes remain visible until they are used, expire, or are explicitly
revoked; a transient pending-list request no longer hides a generated code. - Pairing codes are single-use, expire after 10 minutes, are rate-limited, and
use an unambiguous 32-character alphabet.
Automatic replica discovery
- Replicas now publish their own metrics URL in replication acknowledgements.
- If
NONODB_REPLICATION_ADVERTISE_URLis unset, the daemon infers a LAN URL
from the local interface that routes to the primary and the actual TCP
listener (orNONODB_TCP). - An explicit
NONODB_REPLICATION_ADVERTISE_URLalways wins. It is required
behind NAT, Docker port mapping, a reverse proxy, or TLS termination. - Loopback-only listeners are intentionally not advertised.
- The primary stores advertised replica URLs, and the GUI automatically probes
http://replicas for full Cluster metrics. An ACK-only fallback still shows
the node id, sequence, and freshness when no URL is reachable. /v1/serverexposes the actual listener, advertised URL, version, and
node-local details; the GUI Network tab shows the same information.
Replica lifecycle controls
replication pausestops pulling and applying while keeping the source and
token.replication resumecontinues from the stored source.replication disconnectremoves the source and token and leaves the node
read-only without deleting data.- Remove replica in the GUI deletes the primary-side ACK and remembered URL,
and now persists the removal by blocking further ACKs from that node id. - A live removed replica receives
403 replica_removed. Redeeming a new pairing
code for the same node id unblocks it. - The GUI exposes pause, resume, disconnect, and remove with confirmations.
Multiple daemons on one host
- Added a per-user daemon instance registry:
nonodb-cli instancesnonodb-cli instances --jsonnonodb-cli instances prunenonodb-cli --instance <pid|node_id> ...nonodb-cli --socket <path> ...
- Registry records include PID, node id, role, version, Unix socket, TCP
listener, advertised URL, and data directory. They are runtime metadata only
and are never copied into backups. NONODB_INSTANCE_DIRoverrides the registry directory.- This avoids sending
replication joinorreplication statusto the wrong
local daemon when several instances run on one host.
Network tab and managed firewall
- New Network GUI tab and API:
GET/PUT/DELETE /v1/network;POST /v1/network/firewall/apply;- actual TCP bind, configured
NONODB_TCP, Unix socket, TLS state, and
advertised replication URL.
- Optional nftables management for selected NonoDB ports and source CIDRs, with
rule preview, apply, and managed-table removal. - Firewall apply is opt-in with
NONODB_FIREWALL_MANAGE=1. A non-root daemon can
useNONODB_FIREWALL_SUDO=1with passwordless sudo fornft. - The UI only modifies the dedicated
inet nonodb_firewalltable. It never
replaces SSH or general host firewall policy.
Driver write routing
- The server now returns the primary location in the JSON body of a
403 read_onlyresponse aserror.write_url, in addition to theLocation
header. This lets clients discover the write endpoint without parsing headers. - Opt-in write routing was added to all official drivers:
- Python:
NonoDB(..., write_url=..., auto_primary=...),
NonoDBError.write_url,NONODB_WRITE_URL,NONODB_AUTO_PRIMARY. - Go:
WithWriteURL,WithAutoPrimary,APIError.WriteURL. - Node.js:
ClientOptions.writeUrl,autoPrimary,
NonoDBError.writeUrl. - Rust:
ClientBuilder::write_url,auto_primary,
Error::Api { write_url }.
- Python:
auto_primarydiscovers the write endpoint from/readyz; an explicit
write_urlis also supported.- Routing retries exactly once, and only after an explicit
403 read_only.
It never retries timeouts, connection failures,5xx, or ambiguous outcomes. - Reads, cursors, and watch/stream operations stay on the replica that created
them. - A mixed
batchcontaining any write is routed as a whole to the primary. - SQL routing is best-effort by leading keyword:
SELECT,EXPLAIN,SHOW,
andVALUESstay local;INSERT,UPDATE, andDELETEgo to the primary; a
CTE containing a write is treated conservatively as a write. - TCP primaries still require a token and/or mTLS even when local reads use a
Unix socket.
Documentation and GUI
- Reworked the replication guide around pairing-first onboarding. A paired
replica no longer needs manual source, token, or database environment
variables. - Added Docker replica onboarding, including the requirement to publish a host
port and setNONODB_REPLICATION_ADVERTISE_URLinstead of advertising the
container172.xaddress. - Added driver write-routing examples and the
read_only/write_urlcontract to
the client, API, operations, and replication documentation. - Clarified the supported topology in the README: primary/replica/standby
clusters with quorum failover are supported; sharding and multi-primary
clustering are not. - Corrected stale GUI instructions: the GUI is a separate
nonodb-cli gui
process, not a/guiendpoint served by the daemon. - Internal
cluster-peerandreplica-*credentials no longer count as a
human administrator for the last-admin protection rule.
Breaking changes and upgrade notes
- Replace both
nonodb-daemonandnonodb-clion every node. GUI assets are
embedded innonodb-cli, so restart the GUI process after upgrading. - No storage or API schema migration is required. Existing databases and hidden
.nodestate are reused in place. - Restart daemons after upgrading so they register in the instance registry.
- Pairing is now the recommended onboarding path. Manual
NONODB_REPLICATION_SOURCEandNONODB_REPLICATION_SOURCE_TOKENstill work
for compatibility, but a laterreplication joinoverwrites them. Remove replicais persistent. The primary blocks further ACKs from that node
id until a new pairing code is redeemed for the same id. Use replica-side
pause/disconnect first if the replica must remain offline.- Automatic advertise detection does not traverse NAT, Docker port mapping, a
reverse proxy, or a public DNS name. Se...
v0.25.0-rc.3 - Automatic replica discovery and instance selection
v0.25.0-rc.3 - Automatic replica discovery and instance selection
This release makes replica onboarding automatic on a flat LAN and adds explicit
management for hosts that run more than one daemon.
Highlights
- Replicas now publish their own metrics URL automatically after the first
successful acknowledgement. IfNONODB_REPLICATION_ADVERTISE_URLis unset,
the daemon combines the local interface that routes to the primary with the
actual TCP listener port, so the primary GUI can probe the replica without
hand-written environment variables. - An explicit
NONODB_REPLICATION_ADVERTISE_URLstill takes precedence and is
required behind NAT, Docker port mapping, a reverse proxy, or TLS termination.
Loopback-only listeners are intentionally not advertised. Remove replicais now persistent: the primary blocks further ACKs from that
node id instead of only deleting the old ACK row. A new pairing code for the
same node id unblocks it.- Added a per-user daemon instance registry:
nonodb-cli instancesnonodb-cli instances --jsonnonodb-cli instances prunenonodb-cli --instance <pid|node_id> ...nonodb-cli --socket <path> ...
- Registry records include PID, node id, role, version, socket, TCP listener,
advertised URL, and data directory. They are runtime metadata only and are
never copied into backups. - Updated the CLI, operations, replication, GUI, and Docker documentation for
automatic advertisement, replica removal, and instance selection.
Breaking changes and upgrade notes
- No storage or API schema migration is required.
- Restart daemons after upgrading so they register in the instance directory.
Remove replicanow also blocks the node id. To reconnect a removed replica,
generate a new pairing code and redeem it with the same
NONODB_REPLICATION_NODE_ID.- The LAN auto-detection cannot traverse NAT or discover a public DNS name.
Continue to setNONODB_REPLICATION_ADVERTISE_URLfor those deployments.
Configuration changes
NONODB_INSTANCE_DIRoverrides the per-user instance registry directory.
Defaults are$XDG_RUNTIME_DIR/nonodb/instances,
$HOME/.nonodb/instances, or the platform runtime directory.NONODB_REPLICATION_ADVERTISE_URLremains optional on replicas with a
non-loopback TCP listener and a direct route to the primary.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --locked(all tests passed)python3 scripts/security_check.py(19 passed, 4 warnings, 0 failed)- CI workflow:
43733194146(success) - LiveAPISec workflow:
43733560631(success)
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6af9d89dafda40c778890b64 - Workflow run:
43733560631 - Commit:
8d64c40 - Findings: 0 critical, 0 high, 0 medium, 9 low, 5 info
- Report artifact:
liveapisec-report
Assets
nonodb-v0.25.0-rc.3-linux-x86_64.tar.gzand.sha256nonodb-v0.25.0-rc.3-macos-x86_64.tar.gzand.sha256nonodb-v0.25.0-rc.3-macos-arm64.tar.gzand.sha256nonodb-v0.25.0-rc.3-windows-x86_64.zipand.sha256
Container images are published separately by the Docker workflow for
linux/amd64 and linux/arm64.
Full changelog: v0.25.0-rc.2...v0.25.0-rc.3
v0.25.0-rc.2 - Replica removal and pairing stability
v0.25.0-rc.2 - Replica removal and pairing stability
This pre-release adds explicit replica removal controls and fixes pairing-code visibility in the embedded GUI.
Highlights
- Remove replica in the GUI:
- Replication → Replica connections now has Remove replica;
- Cluster → Dynamic replica connections has the same action;
- removal deletes the primary-side ACK and remembered replica URL immediately.
- CLI/API removal:
nonodb-cli replication forget <node>;DELETE /v1/replication/acks/{node};- optional database-scoped variant.
- Pairing codes stay visible:
- a generated code no longer disappears because of a transient pending-list request failure;
- it is cleared only after a successful refresh proves it was used, after expiry, or after Revoke.
- Operational clarity:
- Remove replica only clears the primary-side row; a still-running replica will reappear after its next ACK;
- use replica-side Pause or Disconnect first when the replica must stay removed.
- Regression fix:
- internal
cluster-peerandreplica-*credentials no longer satisfy the last-human-administrator guard.
- internal
Upgrade notes
- Replace both
nonodb-daemonandnonodb-clion every node. GUI assets are embedded innonodb-cli, so restart the GUI process after upgrading. Remove replicais a primary-side cleanup action, not a remote stop. Stop the replica withreplication pauseorreplication disconnectbefore removing it.- Existing hidden
.nodestate and databases are reused in place. No data migration is required. - No new mandatory environment variables were added in this pre-release.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --locked- auth API integration test
- GUI end-to-end proxy test
- replication CRUD, control-plane, and seed-discovery tests
scripts/security_check.py: 19 passed, 4 warnings, 0 failed- CI run:
43721346663
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6af9ba6bafda40c778890b62 - Workflow run:
43721680891 - Commit:
b0aae93 - Findings: 0 critical, 0 high, 0 medium, 9 low, 5 info
- Tests run: 406
- Report artifact:
liveapisec-report
Assets
- Linux x86_64 archive and SHA-256 checksum
- macOS x86_64 archive and SHA-256 checksum
- macOS arm64 archive and SHA-256 checksum
- Windows x86_64 archive and SHA-256 checksum
Full changelog: v0.25.0-rc.1...v0.25.0-rc.2
v0.25.0-rc.1 - Network firewall and replica controls
v0.25.0-rc.1 - Network firewall and replica controls
This is a pre-release for operators who need the new Network tab, automatic replica discovery, and replica lifecycle controls.
Highlights
- Network tab in the embedded GUI:
- actual TCP bind and configured
NONODB_TCP; - Unix socket path and TLS state;
- advertised replication URL;
- nftables firewall editor for selected NonoDB ports and source CIDRs;
- rule preview, apply, and managed-table removal.
- actual TCP bind and configured
- Replica lifecycle controls:
- pause replication while keeping the source and token;
- resume from the saved source;
- disconnect by removing the source/token while keeping local data and the node read-only.
- Automatic replica discovery in Cluster:
- replicas report
NONODB_REPLICATION_ADVERTISE_URLin acknowledgements; - the primary stores the URL;
- the GUI automatically probes advertised replicas for full metrics;
- ACK-only fallback remains for replicas without a reachable URL.
- replicas report
- Pairing and join feedback:
- used pairing codes disappear from the GUI within one refresh;
replication joinprints a clear connected/source/role summary and waits briefly for the first successful pull;- the primary replica list refreshes every 3 seconds and marks fresh replicas
connected.
- Hardening:
- internal
cluster-peerandreplica-*credentials no longer satisfy the last-human-administrator guard; - source/token handling remains in the hidden
.nodeLMDB state.
- internal
- API additions:
GET/PUT/DELETE /v1/network,POST /v1/network/firewall/apply;POST /v1/replication/pause,/resume, and/disconnect;GET /v1/server;- replica URLs in replication ACK/status output.
Upgrade notes
- Restart the daemon after replacing the binary; the GUI assets are embedded in
nonodb-cli. NONODB_FIREWALL_MANAGE=1is required to apply firewall rules. If the daemon is not root, setNONODB_FIREWALL_SUDO=1only with passwordless sudo fornft.- The firewall editor changes only the dedicated
inet nonodb_firewalltable. It does not modify SSH or a general host firewall. - To expose full metrics in the Cluster view, set
NONODB_REPLICATION_ADVERTISE_URLon every replica to an address reachable from the GUI host. disconnectremoves the replication source and token without deleting local data. The node remains read-only; promote it separately if required.- Existing
.nodestate from0.24.0is reused in place. There is no data migration.
Configuration changes
NONODB_FIREWALL_MANAGE=0
NONODB_FIREWALL_SUDO=0
NONODB_REPLICATION_ADVERTISE_URL=http://10.0.0.50:7912NONODB_FIREWALL_MANAGEenables apply/disable operations.NONODB_FIREWALL_SUDOrunsnftthroughsudo -nfor a non-root daemon.NONODB_REPLICATION_ADVERTISE_URLis now also sent in replication ACKs.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --locked- replication CRUD, control-plane, discovery, lease-gate, vault, and partition tests
- GUI end-to-end proxy test
scripts/security_check.py: 19 passed, 4 warnings, 0 failed- CI run:
43708349451
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6af996383512d54c7e132882 - Workflow run:
43708641141 - Commit:
db74eca - Findings: 0 critical, 0 high, 0 medium, 9 low, 5 info
- Tests run: 400
- Report artifact:
liveapisec-report
Assets
- Linux x86_64 archive and SHA-256 checksum
- macOS x86_64 archive and SHA-256 checksum
- macOS arm64 archive and SHA-256 checksum
- Windows x86_64 archive and SHA-256 checksum
Full changelog: v0.24.0...v0.25.0-rc.1
v0.24.0 - Cluster control plane, seed discovery, and replica pairing
Highlights
- Replicate the cluster control plane: auth registry, backup jobs/state,
database catalog, and cluster peer token. - Store node-local replication state (role, source, epoch, lease, peer token,
pairing codes) in the hidden.nodeLMDB system collection. Legacy JSON
files are imported once and removed. - Rediscover the current primary through
NONODB_REPLICATION_SEEDS, voters,
and followers after the stored source becomes unreachable. - Persist replica pairing codes, keep them one-time and short-lived (10 minutes),
and expose pairing in both CLI and GUI. - Use the primary's actual
Write URLin the GUI Add replica panel instead of
hardcoding the GUI proxy port. Added end-to-end screenshots and a step-by-step
replica enrollment guide. - Harden quorum lease/failover, divergent replica resync, partition recovery,
and encrypted vault envelope replication. - Fix
nonodb-cli replication add-replicaoutput to print the effective join
URL and warn that the default daemon API port is 7878, not GUI proxy 8787.
Upgrade notes
- Back up
NONODB_DATAbefore upgrading. .nodeis node-local: do not copy it to another node.- Set
NONODB_REPLICATION_SEEDSon replicas for primary rediscovery. replication joinuses the daemon API URL (default port 7878), not the GUI
proxy port (default 8787).- Use
RUST_LOGfor daemon log level.NONODB_LOGis not read by the daemon. - Replication remains asynchronous; replication is not a backup.
Validation
cargo test --locked --workspace --all-targets --all-featurescargo clippy --locked --workspace --all-targets --all-features -- -D warnings- GUI production build and GUI E2E tests
- Replication control-plane, discovery, failover, lease-gate, partition, vault,
and GUI cluster tests - Python/Node/Go client checks
Documentation
- Updated replication/cluster guide, CLI guide, GUI guide, operations, roadmap,
version references, and release screenshots underdocs/assets/gui/.
v0.23.0 - Replication and cluster operations
v0.23.0 - Replication and cluster operations
NonoDB 0.23.0 adds the first complete replication and cluster operation set:
asynchronous primary/replica replication, hot standby, quorum promotion,
leases, automatic election, write routing, and a cluster-wide GUI.
Replication is opt-in. A single-node deployment behaves as before unless
NONODB_REPLICATION_ENABLED=1 is set on a writer.
Highlights
- Durable ordered replication log. Every committed write transaction is
recorded with origin, sequence, epoch, document changes, and ordered metadata
operations. - Read replicas and hot standby. Replicas pull over HTTP/TLS/mTLS, apply
atomically and idempotently, and reject client writes with403 read_only. - Snapshot bootstrap. A fresh or badly lagging replica can seed itself from
a consistent snapshot, then continue from the ordered log. - Metadata replication. Collection creation, TTL, history settings,
automatic-event settings, secondary/text/fuzzy/vector/geo indexes, and
conditional subscriptions are replicated and applied in order. - Events and live watch. Replicated
_eventsdocuments remain watchable on
replicas; live NDJSON/SSE notifications are dispatched after replica commit. - History and TTL. Replicas generate history from replicated before/after
values and keep replicated TTL configuration. TTL expiry remains
primary-driven and is applied as replicated deletes. - Replica acknowledgements and safe retention. Replicas report applied
sequences; the primary can prune only up to the minimum ack and exposes
ack-age metrics. - Quorum failover. Voter-majority promotion, persisted votes, primary
leases with self-demotion, candidate election, and source propagation to
voters and followers. - Write routing discovery.
write_url,GET /v1/replication/primary,
GET /readyz/write, and aLocationheader on read-only write rejections
let clients and proxies find the current writer. - TLS rotation. Server certificates, keys, and the client CA reload without
a daemon restart; replication clients rebuild TLS settings each pull. - GUI Cluster view. One page shows every configured node with role, epoch,
head, lag, acks, transport health, write URL, source, requests, errors, disk,
and offline state. The Replication page explains every field inline and
exposes source/role controls. - Live load-test progress. The Cluster tab can show benchmark phase,
documents loaded, rate, online nodes, writes, primary, and epoch. - Operational tests. New multi-host cluster, failover, lease, election,
metadata, TLS reload, GUI cluster, and large-load scripts.
What is replicated
Document inserts, updates, deletes, atomic batches, SQL writes, TTL deletes,
collection metadata, indexes, history, automatic events, subscription
definitions, and outbox events.
Not replicated: vault document contents, the auth registry, backup jobs,
node-local configuration, and create_database / drop_database. Background
workers must target the primary or write_url.
Breaking changes and upgrade notes
- Version bumped to
0.23.0in the workspace, Node client, GUI package, Docker
Compose defaults, and documentation. - Internal collection names
meta,history,ttl, and_replicationare now
rejected as user collection names. Rename any existing collection that uses
one of these names before upgrading. - Replication requires the source token to have
admin:db(or*:*). There is
no narrower replication-only scope yet. - Replicas are read-only. Point writers, imports, and job workers at the primary
or the advertisedwrite_url. - A replica that bootstraps from a snapshot must use a fresh or disposable data
directory; do not merge a snapshot into a live database directory. - For large write transactions, use
NONODB_REPLICATION_BATCH=10or20.
This avoids very large/v1/replication/changesresponses and memory spikes. - Existing single-node databases need no migration; replication state is
created only when replication is enabled.
Configuration
New settings include:
NONODB_REPLICATION_ENABLED, NONODB_REPLICATION_ORIGIN,
NONODB_REPLICATION_ROLE, NONODB_REPLICATION_NODE_ID,
NONODB_REPLICATION_SOURCE, NONODB_REPLICATION_SOURCE_TOKEN,
NONODB_REPLICATION_DATABASES, NONODB_REPLICATION_POLL_INTERVAL,
NONODB_REPLICATION_BATCH, NONODB_REPLICATION_BOOTSTRAP,
NONODB_REPLICATION_ADVERTISE_URL, NONODB_REPLICATION_VOTERS,
NONODB_REPLICATION_VOTER_TOKEN, NONODB_REPLICATION_FOLLOWERS,
NONODB_REPLICATION_LEASE_INTERVAL, NONODB_REPLICATION_LEASE_TTL,
NONODB_REPLICATION_AUTO_FAILOVER, NONODB_REPLICATION_CANDIDATE,
NONODB_REPLICATION_CANDIDATE_PRIORITY,
NONODB_REPLICATION_ELECTION_INTERVAL,
NONODB_REPLICATION_FAILOVER_TIMEOUT, NONODB_REPLICATION_PRUNE_INTERVAL,
NONODB_REPLICATION_RETENTION_KEEP, NONODB_REPLICATION_CA_FILE,
NONODB_REPLICATION_CERT_FILE, NONODB_REPLICATION_KEY_FILE, and
NONODB_TLS_RELOAD_INTERVAL.
See the replication and cluster guide
for primary/replica setup, TLS, GUI, CLI, failover, monitoring, and
troubleshooting.
Validation performed
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --locked- replication snapshot/pull/apply/epoch/promotion test
- metadata, index, history, event, subscription, TTL, and live-watch test
- quorum failover, lease self-demotion, and automatic election tests
- TLS hot-reload test
- GUI and GUI cluster tests
- multi-host cluster test with dynamic joins, acks, failover, and convergence
- large 7-node load test: 1M documents, two failovers, peak primary RSS 775 MB,
final 1,018,454 documents across five surviving nodes - CI run
43611561836 - LiveAPISec workflow run
43611873851
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6af882456cdd24ed1e3acc28 - Workflow run:
43611873851 - Commit:
fac70dadb1e31bc9ddc68a3e21f0436fb9012515 - Findings: 0 critical, 0 high, 0 medium, 9 low, 5 info
- Tests: 400
- Report artifact:
liveapisec-report
Local scripts/security_check.py: 19 passed, 4 warnings, 0 failed.
Assets
Release archives are produced by GitHub Actions for:
- Linux x86_64
- macOS x86_64
- macOS arm64
- Windows x86_64
Each archive has a SHA-256 checksum.
Container image: ghcr.io/essmos/nonodb:0.23.0 (linux/amd64 and linux/arm64),
also published as 0.23 and latest.
Full changelog
v0.22.0 - Backup import, compression, and safer GUI operations
v0.22.0 - Backup import, compression, and safer GUI operations
This release turns the backup area into a complete operational workflow: create
different backup variants from the GUI, inspect their metadata, verify them, and
import them safely as new databases.
Highlights
- GUI backup jobs now support:
- full native copies and restic incremental/deduplicated repositories;
- multi-select databases in one job;
- per-collection exclusions applied to the backup copy only;
- gzip compression before optional age encryption;
- local filesystem and S3/Cloudflare R2 destinations;
- restic local and S3 repository destinations;
- age key generation and restic password generation without exposing secrets;
- Save & run now, live status refresh, completion notices, and the last
destination path.
- Every native backup now includes a human-readable
backup-info.txtwith
database, job, checksum, compression, encryption, exclusions, scope, verify and
restore instructions, and the as-is warning. It is uploaded to S3 and included
in restic snapshots. - New GUI Import wizard:
- browses backups in local folders or S3/R2 prefixes;
- verifies checksum, decrypts age, decompresses gzip, and deep-verifies LMDB;
- imports as a new database and never overwrites a live database.
- Required GUI backup disclaimer before creating or running jobs.
- GUI backup and import documentation with screenshots.
- Auth management API and GUI: principals, one-time tokens, mTLS certificates,
enable/disable, last-admin protection, and referenced-principal checks. - Native Prometheus endpoint,
metrics:readscope, readiness checks, disk and
snapshot metrics, per-collection metrics, and OpenTelemetry Collector guidance. - Database storage statistics and revised GUI information architecture.
- English-only GUI and translated user-visible daemon/core errors.
Configuration
New environment variables:
NONODB_BACKUP_KEY_DIR— generated age/restic key directory, default
<NONODB_DATA>/backup-keys.NONODB_IMPORT_ROOTS— allowed local roots for the Import wizard, default
<NONODB_DATA>/backups.
New defaults for new backup jobs:
- local destination:
<NONODB_DATA>/backups; - local restic repository:
<NONODB_DATA>/restic-repo.
Existing jobs keep their configured paths.
New endpoints:
GET /metrics/prometheusGET /readyz/v1/auth,/v1/auth/principals,/v1/auth/tokens,/v1/auth/certificates/v1/backups/keygen,/v1/backups/secret/v1/import,/v1/import/browse,/v1/import/run,
/v1/import/status/{id}
Upgrade notes
- Backups now contain
backup-info.txt. Native S3 jobs upload an additional
object; automation that assumed exactly two S3 objects should account for it. - Import currently supports full native local/S3 backups. Selective collection
import and restic repository import are planned for a later release. - Imaging and release assets remain built only by GitHub Actions.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --lockedpython3 scripts/auth_api_test.pypython3 scripts/backup_api_test.pypython3 scripts/gui_test.pypython3 scripts/security_check.py— 19 passed, 4 warnings, 0 failed- LiveAPISec — scan
6af773f8ba45fabbd33e2fe4, 413 tests, findings
info=6,low=9, no critical/high/medium findings.
Assets
- Linux x86_64
.tar.gz+ SHA-256 - macOS x86_64
.tar.gz+ SHA-256 - macOS arm64
.tar.gz+ SHA-256 - Windows x86_64
.zip+ SHA-256
Full changelog
v0.21.0 - Multiple databases in one daemon
v0.21.0 - Multiple databases in one daemon
NonoDB can now host multiple independent databases inside one daemon, on one
socket or TCP port. Each database is a separate LMDB environment under
NONODB_DATA/<database>/ with its own writer, read cache, automatic indexes,
maintenance loop, TTL/history/event settings, and persistent subscriptions.
There are no cross-database queries, joins, or transactions; isolation is the
point.
Highlights
- Database routing.
POST /{database}/v1/execand
POST /{database}/v1/watchselect a database. The existing/v1/execand
/v1/watchpaths remain aliases fordefault, so single-database clients
keep working. - Database management API.
list_databases,create_database, and
drop_database.defaultcannot be dropped, and a database cannot be dropped
while an active request is using it. - CLI support.
--db <name>/NONODB_DB,databases list|create|drop,
backup-all,restore-all,sync, and database selection for every
daemon-facing command. - GUI support. A database selector in the sidebar and a
Databasefield in
Advanced connection settings. The embedded GUI manages all databases through
one process and port. - Database-qualified authorization. Scopes such as
read:app1/orders,
write:app1/*, andadmin:app1/ordersrestrict access to one database.
Unqualified scopes still apply to every database;admin:dbremains
instance-wide. - Lifecycle controls. Databases open lazily, idle environments can be
evicted, andNONODB_MAX_OPEN_DATABASES(default64) bounds open writers.
Unknown databases return404 not_found; exhausting all open slots returns
503 database_limit. - Per-database state. Writers, read caches, auto-index state, maintenance,
snapshots, TTL, history, events, subscriptions, and map settings are all
scoped to one database. - Backup and restore.
backup/restoretarget one database;
backup-all/restore-allcopy a whole instance with an instance manifest.
Snapshot directories are created per database. - Official clients. Python, Rust, Node.js, and Go accept an explicit
database and fall back toNONODB_DB, thendefault. - Automatic migration. A legacy root-level
data.mdbis moved to
default/data.mdbon startup. If both layouts exist, the daemon refuses to
guess and exits with a clear error.
Also in this release
- Per-request write durability:
full(default),relaxed, and opt-in
unsafe, plus thesyncoperation andnonodb-cli sync. Durability changes
fsync behavior only; writes remain atomic. Group commit uses the strictest
mode in the batch, and background maintenance always usesfull. - Database-aware cursors, live subscriptions, metrics, and auth checks.
- Updated README, GUI screenshots, video, architecture, API, auth, CLI,
operations, backup, client, and multi-database documentation.
Upgrade notes
- Stop the daemon and take a backup before upgrading.
- The first
0.21.0start migrates a legacydata.mdb,lock.mdb, and
auto-index.jsonintodefault/. Ifdefault/data.mdbalso exists, startup
aborts instead of overwriting either copy. - Existing
/v1/execand/v1/watchclients continue to use thedefault
database. No URL change is required for single-database deployments. - Unqualified scopes such as
read:ordersstill apply to every database. Add a
database prefix to restrict a principal in a multi-database deployment. - For backups of all databases, use
nonodb-cli backup-all;backupnow
targets one selected database. Restore withrestore-allor with--db. - There are no cross-database transactions. If an application requires a
consistent recovery point across databases, quiesce writes during
backup-all.
Configuration
| Variable | Default | Purpose |
|---|---|---|
NONODB_MAX_OPEN_DATABASES |
64 |
Maximum simultaneously open LMDB environments/writers |
NONODB_DB |
default |
Database selected by CLI and official clients |
NONODB_ALLOW_UNSAFE_WRITES |
unset | Enables opt-in durability:"unsafe" |
Reserved database names: v1, healthz, metrics, gui, db, api.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --lockedpython3 scripts/multi_database_test.pypython3 scripts/multi_database_features_test.pypython3 scripts/durability_test.py
Assets
Release workflow builds Linux x86_64, macOS x86_64, macOS arm64, and Windows
x86_64 archives. Each archive has a SHA-256 checksum file. Docker images are
published as ghcr.io/essmos/nonodb:0.21.0, :0.21, and :latest.
Full changelog: v0.20.0...v0.21.0
v0.20.0 - GUI login and authentication
v0.20.0 - GUI login and authentication
The GUI now uses the same NonoDB database token as the CLI and API, with a much
simpler connection screen. Local sessions can fill the token automatically from
NONODB_TOKEN, while gui --url makes the proxy use daemon TCP so bearer-token
authentication is actually enforced.
Highlights
- Simplified GUI login:
- a single Database token field;
- no separate GUI account or password;
- endpoint, saved profiles, vault tenant/key id/key moved under Advanced;
- clear note that the token is the same credential used by
nonodb-cliand API
clients.
- Added local session defaults:
- new same-origin
/gui/sessionendpoint; - when the GUI process starts with
NONODB_TOKEN, the token is filled
automatically; - no token is embedded in the static bundle or HTML.
- new same-origin
- Added
nonodb-cli gui --url:- connects the local GUI proxy to a daemon TCP listener;
- forwards bearer tokens to the daemon;
- required when daemon token authentication must be enforced;
- documents that Unix sockets are trusted local-admin connections and do not
require tokens.
- Improved authentication behavior:
- unauthenticated GUI API calls now return
401 unauthorizedwhen the GUI
uses an authenticated TCP endpoint; - valid tokens are forwarded unchanged and the daemon enforces read, write,
and admin scopes; - vault credentials remain a separate Advanced option.
- unauthenticated GUI API calls now return
- Updated documentation:
- login and token behavior in
docs/gui.md; --urlindocs/cli.md;- local-vs-TCP auth guidance and upgrade notes.
- login and token behavior in
Behavior and limitations
- The GUI still has no separate user database. NonoDB uses bearer tokens, not
usernames and passwords. - Local Unix-socket connections remain trusted
local_adminconnections. To
require a token, run the daemon with a TCP listener and start the GUI with
--url http://127.0.0.1:<port>. - Tokens are stored in browser
sessionStorage; saved profiles use
localStorage. Do not save production tokens on a shared machine. - Vault tenant, key id, and key are still separate from the login token.
- No database format migration is required.
Validation performed
npm run buildcargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --lockedpython3 scripts/gui_test.py- authenticated TCP check: unauthenticated request returns
401, valid bearer
token returns200 /gui/sessiontoken auto-fill check withNONODB_TOKEN
Upgrade notes
- This is an additive release.
- Existing GUI usage without daemon auth continues to work.
- To force login, start the daemon with
NONODB_AUTH_FILEandNONODB_TCP,
then runnonodb-cli gui --url http://127.0.0.1:<port>. - No configuration changes are required for local unauthenticated use.
Assets
nonodb-v0.20.0-linux-x86_64.tar.gz+ SHA-256nonodb-v0.20.0-macos-x86_64.tar.gz+ SHA-256nonodb-v0.20.0-macos-arm64.tar.gz+ SHA-256nonodb-v0.20.0-windows-x86_64.zip+ SHA-256
Full changelog: v0.19.0...v0.20.0