Files

T

dimgigov 215df1cdf3 docs: update README and all docs with formal verification, new BaraQL features, OpenTelemetry tracing

- Add Formal Verification section to README and architecture docs
- Document TLA+ specs for Raft, 2PC, MVCC, Replication
- Add new BaraQL features: JSON path (->, ->>), FTS @@, CREATE INDEX USING FTS,
  RECOVER TO TIMESTAMP, UNION/INTERSECT/EXCEPT
- Add OpenTelemetry tracing example to README
- Update Quick Start to use nimble test/bench
- Update EN and BG documentation

2026-05-07 16:06:13 +03:00

2.3 KiB

Raw Blame History

Distributed Systems

BaraDB supports distributed deployment with Raft consensus, sharding, and replication.

Raft Consensus

Leader election and log replication:

import barabadb/core/raft

var cluster = newRaftCluster()
cluster.addNode("node1")
cluster.addNode("node2")
cluster.addNode("node3")

let n1 = cluster.nodes["n1"]
n1.becomeCandidate()
n1.becomeLeader()
let entry = n1.appendLog("SET key1 value1")

Sharding

Distribute data across nodes:

import barabadb/core/sharding

var router = newShardRouter(ShardConfig(
  numShards: 4,
  replicas: 2,
  strategy: ssHash
))
router.rebalance(@["node1", "node2", "node3"])
let shard = router.getShard("user_123")

Sharding Strategies

Strategy	Description
`ssHash`	Hash-based sharding
`ssRange`	Range-based sharding
`ssConsistent`	Consistent hashing

Replication

import barabadb/core/replication

var rm = newReplicationManager(rmSync)
rm.addReplica(newReplica("r1", "10.0.0.1", 9472))
rm.connectReplica("r1")
let lsn = rm.writeLsn(@[1'u8, 2, 3])
rm.ackLsn("r1", lsn)

Replication Modes

Mode	Description
`rmSync`	Synchronous replication
`rmAsync`	Asynchronous replication
`rmSemiSync`	Semi-synchronous replication

Gossip Protocol

Membership and failure detection:

import barabadb/core/gossip

var g = newGossipManager()
g.addNode("node1")
g.addNode("node2")
g.tick()  # Exchange membership info

Distributed Transactions

Two-phase commit across nodes:

import barabadb/core/disttxn

var dt = newDistributedTxn()
dt.prepare(@["node1", "node2"])
dt.commit()

Formal Verification

Core distributed algorithms are formally specified in TLA+ and model-checked:

Raft Consensus — formal-verification/raft.tla
- Verified: ElectionSafety, StateMachineSafety
Two-Phase Commit — formal-verification/twopc.tla
- Verified: Atomicity, NoOrphanBlocks
Replication — formal-verification/replication.tla
- Verified: MonotonicLsn, AcksRemovePending

Run TLC locally:

cd formal-verification
java -cp tla2tools.jar tlc2.TLC -config models/raft.cfg raft.tla
java -cp tla2tools.jar tlc2.TLC -config models/twopc.cfg twopc.tla
java -cp tla2tools.jar tlc2.TLC -config models/replication.cfg replication.tla

2.3 KiB Raw Blame History