The Server (Raft)
patinadb-raft is the patinaDB server: a standalone node that holds one
or more databases, replicates writes with the Raft consensus protocol
(openraft 0.9), and exposes both a JSON REST API and the native Bolt
protocol. It scales from a single self-leading node (a plain server with no
consensus latency) up to a highly-available multi-node cluster with automatic
failover.
Running a node
patinadb-raft \
--id 1 \
--addr 127.0.0.1:21001 \
--db ./data \
--bootstrap \
--bolt-addr 127.0.0.1:7687 \
--auth-user neo4j \
--auth-password secret
| Flag | Default | Meaning |
|---|---|---|
--id <u64> | (required) | Unique Raft node id within the cluster. |
--addr <host:port> | (required) | HTTP listen address (REST + peer RPCs + management). |
--db <dir> | (required) | Database root directory — one subdirectory per database. |
--bootstrap | off | Initialize a single-voter cluster so this node leads itself immediately. |
--bolt-addr <addr> | 127.0.0.1:7687 | Bolt listener. "" disables Bolt. |
--advertised-addr | = --bolt-addr | Bolt address advertised in routing / SHOW DATABASES (set behind proxy). |
--auth-user <name> | neo4j | Username for REST Basic / Bolt LOGON / peer RPCs. |
--auth-password <p> | "" (open!) | Shared password. Empty = authentication disabled. Also PATINADB_AUTH_PASSWORD. |
--bootstrapis the easy button. One node with--bootstrapis a complete, working server — it elects itself leader and accepts writes with no further setup. You only need the management endpoints when growing to multiple nodes.
What a node exposes
- REST on
--addr— see REST API. - Bolt on
--bolt-addr— see Bolt & Neo4j Browser. - Management & peer RPC on
--addr—/mgmt/init,/mgmt/add-learner,/mgmt/change-membership,/mgmt/metrics,/health,/version, and the internal/raft/*receivers.
The replication model
Every write is turned into a deterministic batch of delta operations and
committed through Raft as one log entry. Every node applies the committed
entry to its own local graph — there is no leader/follower divergence and no
separate read-replica path for data: a read on any node serves that node’s
applied state. DDL control commands (CREATE/DROP DATABASE,
CREATE/DROP FULLTEXT INDEX) replicate the same way.
The leader resolves a Cypher write against an ephemeral mirror of HEAD to
capture the concrete ops without mutating anything locally, then proposes
Write { db, ops }; the actual mutation happens uniformly when the entry
commits and every node applies it.
Durability
Both the Raft log and the state machine are redb-backed and persistent: the
log survives restart, and last_applied is persisted so a restart resumes
without re-applying the whole log. The graph itself is already on disk. A node
can be killed and restarted and it rejoins with its state intact.
Continue with REST API, Bolt & Neo4j Browser, Multi-Database, High Availability, and Authentication & TLS.