Skip to content

v0.25.0 - Replication controls, automatic discovery, and driver write routing

Choose a tag to compare

@github-actions github-actions released this 15 Nov 18:43

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 K7M4P9QX

On 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 status

After 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 join now installs the source URL, source token, database list,
    poll interval, batch size, and bootstrap mode from the primary. Operators no
    longer need to copy NONODB_REPLICATION_SOURCE,
    NONODB_REPLICATION_SOURCE_TOKEN, or NONODB_REPLICATION_DATABASES into a
    paired replica.
  • Joining demotes a writable node to a read-only replica, stores the returned
    source and token in the hidden .node state, 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_URL is unset, the daemon infers a LAN URL
    from the local interface that routes to the primary and the actual TCP
    listener (or NONODB_TCP).
  • An explicit NONODB_REPLICATION_ADVERTISE_URL always 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/server exposes the actual listener, advertised URL, version, and
    node-local details; the GUI Network tab shows the same information.

Replica lifecycle controls

  • replication pause stops pulling and applying while keeping the source and
    token.
  • replication resume continues from the stored source.
  • replication disconnect removes 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 instances
    • nonodb-cli instances --json
    • nonodb-cli instances prune
    • nonodb-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_DIR overrides the registry directory.
  • This avoids sending replication join or replication status to 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
    use NONODB_FIREWALL_SUDO=1 with passwordless sudo for nft.
  • The UI only modifies the dedicated inet nonodb_firewall table. 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_only response as error.write_url, in addition to the Location
    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 }.
  • auto_primary discovers the write endpoint from /readyz; an explicit
    write_url is 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 batch containing any write is routed as a whole to the primary.
  • SQL routing is best-effort by leading keyword: SELECT, EXPLAIN, SHOW,
    and VALUES stay local; INSERT, UPDATE, and DELETE go 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 set NONODB_REPLICATION_ADVERTISE_URL instead of advertising the
    container 172.x address.
  • Added driver write-routing examples and the read_only/write_url contract 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 /gui endpoint served by the daemon.
  • Internal cluster-peer and replica-* credentials no longer count as a
    human administrator for the last-admin protection rule.

Breaking changes and upgrade notes

  • Replace both nonodb-daemon and nonodb-cli on every node. GUI assets are
    embedded in nonodb-cli, so restart the GUI process after upgrading.
  • No storage or API schema migration is required. Existing databases and hidden
    .node state 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_SOURCE and NONODB_REPLICATION_SOURCE_TOKEN still work
    for compatibility, but a later replication join overwrites them.
  • Remove replica is 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_URL explicitly 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=1

NONODB_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 --check
  • cargo clippy --workspace --all-targets -- -D warnings
  • cargo test --workspace --locked
  • python3 client/routing_test.py
  • node client/node/routing_test.js
  • cd client/go && go test ./...
  • cargo test -p nonodb-client
  • python3 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