photoncloud-monorepo/specifications/flaredb/004-multi-raft/quickstart.md

Quickstart: Multi-Raft (Static → Split → Move)

Prerequisites

• Nix or Rust toolchain per repo.
• PD stub runs inline (tests use in-memory).

Run tests (recommended)

nix develop -c cargo test -q rdb-server::tests::test_multi_region
nix develop -c cargo test -q rdb-server::tests::test_split
nix develop -c cargo test -q rdb-server::tests::test_confchange_move

Or full suite:

nix develop -c cargo test -q

Manual smoke (single node, two regions)

1. Launch PD stub (or ensure pdpb gRPC reachable).
2. Start server:

   nix develop -c cargo run -p rdb-server -- --pd-endpoint http://127.0.0.1:50051
   

3. Verify routing:
   • Put key b"a" → Region1
   • Put key b"z" → Region2

Trigger split (dev)

1. Run test_split or fill a region with writes.
2. Observe log: ApplyCommand::Split and new region registered.

Move (rebalance) flow (simplified)

1. Source store handles region; target store starts with PD meta.
2. PD issues MoveRegion(region_id, from=src, to=dst).
3. Source adds replica on target (ConfChange Add); target catches up; source can later remove itself (ConfChange Remove).
4. Verify data on target:

   nix develop -c cargo test -q move_region_replica_carries_data -- --nocapture
   

Notes

• Key ranges must not overlap; nodes validate PD meta.
• Raft logs and hard-state are prefixed by region_id to isolate shards.
• Pending eventual writes are forwarded to leaders; local queue persists to disk to survive restart.