Running a skaidb cluster

skaidb is leaderless: every node serves reads and writes, data is placed on a consistent-hash ring (virtual nodes), and each key is replicated to the next replication_factor nodes clockwise. Writes wait for a tunable quorum; reads gather from replicas and resolve by last-writer-wins with a deterministic tie rule, so an exact cross-node stamp collision resolves the same way on every replica, never by arrival order. Clustered UPDATEs and INSERT … ON CONFLICT upserts additionally serialize per row through a per-key consensus round, so concurrent read-modify-writes of one row never lose updates, and every write error says whether a retry is safe. There is no primary to configure.

This guide is split by task. Each page stands on its own; start with the one that matches what you are doing.

Pages

Page	Read it when
Setting up a cluster	You are forming a cluster: what makes a node a member, ports, the seed list, three nodes on three machines or on one, verifying the ring.
Replication, consistency and ordering	You need to know what an acknowledgement means: replication factor, ONE/QUORUM/ALL, how indexes and counts behave at each level, linearizable UPDATEs and hot keys, every write error and what a retry means, write ordering, clock skew.
Small clusters: one, two and three members	You are deciding how many members to run, or you run two and want to know exactly what a member outage costs.
Table placement, partitions and transactions	A table needs its own replication factor or a fixed set of nodes, rows must be co-located for single-shard transactions, you use BEGIN ATOMIC, or you have foreign keys on a cluster.
Adding, removing and replacing members	You are joining a node, decommissioning one, forcing out a dead one, or rebuilding a member whose data directory is gone.
Operating a cluster day to day	Rolling restarts and upgrades, backups and point-in-time recovery, what the node does under damage, memory pressure, a full disk and a stop signal, and the operational limits.
Anti-entropy, repair and space reclamation	You want to understand or drive convergence: read-repair, hinted handoff, digest-gated passes, REPAIR CLUSTER, RECLAIM, a wedged engine lock, auditing a member's indexes with CHECK INDEX.
Securing a cluster	Internode authentication and certificate rotation, client TLS, at-rest encryption and KEK rotation.
Witness and BI nodes	You want a continuous off-site mirror, a partial mirror, or a node dedicated to dashboards.

A first cluster, in order

1. Set it up: three members on three machines is the smallest configuration that rides out a member restart without any statement failing. Small clusters explains what one or two members can and cannot do.
2. Choose the consistency defaults: ONE for throughput and availability, QUORUM where a read must see the latest acknowledged write. UPDATEs are linearizable at every level.
3. Secure it before it leaves the lab: internode mTLS, client TLS, at-rest encryption.
4. Learn the day-to-day moves, the rolling restart first, and let anti-entropy do the rest.

Related

• RESHARDING.md: the mechanics of membership changes and data movement (pending ranges, dual writes, drains, throttling).
• GLOBAL_INDEXES.md: value-sharded indexes on clusters with more members than copies.
• METRICS.md: every cluster metric, with alerting hints.
• INSTALL.md and DOCKER.md: getting the binary onto each machine.