Repository navigation
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. Set
NONODB_REPLICATION_ADVERTISE_URLexplicitly for those deployments. - Clusters remain single-writer. There is no sharding and no multi-primary mode.
- Failover remains asynchronous. A small RPO window exists unless writes are
stopped before promotion; divergent writes from an isolated old primary are
discarded on resync, not merged.
Configuration changes
# Optional: explicit replica URL for ACK/GUI discovery.
NONODB_REPLICATION_ADVERTISE_URL=http://10.0.0.50:7912
# Optional: per-user daemon instance registry.
NONODB_INSTANCE_DIR=/run/user/1000/nonodb/instances
# Optional: managed nftables table for NonoDB ports.
NONODB_FIREWALL_MANAGE=0
NONODB_FIREWALL_SUDO=0
# Optional driver-side write routing.
NONODB_WRITE_URL=http://10.0.0.10:7878
NONODB_AUTO_PRIMARY=1NONODB_REPLICATION_BATCH is copied from the primary into the pairing response.
Set it to 10 or 20 on the primary before creating a pairing code when very
large write transactions cause /v1/replication/changes responses to be large.
Validation
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace --lockedpython3 client/routing_test.pynode client/node/routing_test.jscd client/go && go test ./...cargo test -p nonodb-clientpython3 scripts/security_check.py- Replication, control-plane, discovery, lease-gate, vault, partition, and GUI
cluster integration tests - End-to-end write routing against a real read replica for Python, Node.js, Go,
and Rust: write rejected by the replica, routed to the primary, visible on the
primary, then cleaned up - Release CI run: recorded from the release workflow
- LiveAPISec workflow: 43747285839
LiveAPISec.com
LiveAPISec.com tests: passed
- Scan:
6af9fa2f991a96d9890b5dde - Workflow run:
43747285839 - Commit:
704fd5b - Findings: 0 critical, 0 high, 0 medium, 4 low, 9 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
Container images for linux/amd64 and linux/arm64 are published separately by
the Docker workflow to ghcr.io/essmos/nonodb.
Full changelog: v0.24.0...v0.25.0