centra
8f94aee1fa
- Remove gitlinks (160000 mode) for chainfire, flaredb, iam - Add workspace contents as regular tracked files - Update flake.nix to use simple paths instead of builtins.fetchGit This resolves the nix build failure where submodule directories appeared empty in the nix store. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
78 lines
3.1 KiB
Markdown
78 lines
3.1 KiB
Markdown
# Quickstart: Namespace Consistency Modes
|
|
|
|
This guide shows how to operate namespace-level consistency (strong vs eventual) now that runtime mode updates are supported.
|
|
|
|
## Boot a local cluster
|
|
|
|
```bash
|
|
# Start three nodes with explicit namespace modes (default=strong, logs=eventual)
|
|
cargo run -p rdb-server -- --store-id 1 --addr 127.0.0.1:50051 --namespace-mode logs=eventual
|
|
cargo run -p rdb-server -- --store-id 2 --addr 127.0.0.1:50052 --peer 1=127.0.0.1:50051 --namespace-mode logs=eventual
|
|
cargo run -p rdb-server -- --store-id 3 --addr 127.0.0.1:50053 --peer 1=127.0.0.1:50051 --namespace-mode logs=eventual
|
|
```
|
|
|
|
## Inspect current modes
|
|
|
|
`RaftService/GetMode` (single namespace) and `RaftService/ListNamespaceModes` (all namespaces) expose the active configuration and whether a namespace was implicitly created from the default.
|
|
|
|
```bash
|
|
# List all namespaces and their modes
|
|
grpcurl -plaintext 127.0.0.1:50051 raftpb.RaftService/ListNamespaceModes
|
|
|
|
# Check a specific namespace
|
|
grpcurl -plaintext -d '{"namespace":"logs"}' 127.0.0.1:50051 raftpb.RaftService/GetMode
|
|
```
|
|
|
|
The response includes `from_default=true` when the namespace was auto-created using the default mode.
|
|
|
|
## Update a namespace mode (rolling safe)
|
|
|
|
Mode updates are applied in-memory and picked up immediately by peers; roll across nodes to avoid divergence.
|
|
|
|
```bash
|
|
# Switch "logs" to strong consistency on node 1
|
|
grpcurl -plaintext -d '{"namespace":"logs","mode":"strong"}' \
|
|
127.0.0.1:50051 raftpb.RaftService/UpdateNamespaceMode
|
|
|
|
# Repeat on each node; verify all agree
|
|
grpcurl -plaintext 127.0.0.1:50051 raftpb.RaftService/ListNamespaceModes
|
|
grpcurl -plaintext 127.0.0.1:50052 raftpb.RaftService/ListNamespaceModes
|
|
grpcurl -plaintext 127.0.0.1:50053 raftpb.RaftService/ListNamespaceModes
|
|
```
|
|
|
|
If nodes return different modes for the same namespace, treat it as a mismatch and reapply the update on the outlier nodes.
|
|
|
|
## Client usage (KV)
|
|
|
|
Strong namespaces use CAS/read/write through the Raft leader; eventual namespaces accept `RawPut/RawGet` locally with LWW replication.
|
|
|
|
```bash
|
|
# Eventual write/read
|
|
grpcurl -plaintext -d '{"namespace":"logs","key":"a","value":"b"}' \
|
|
127.0.0.1:50051 kvrpc.KvRaw/RawPut
|
|
grpcurl -plaintext -d '{"namespace":"logs","key":"a"}' \
|
|
127.0.0.1:50052 kvrpc.KvRaw/RawGet
|
|
|
|
# Strong write/read
|
|
grpcurl -plaintext -d '{"namespace":"default","key":"a","value":"b","expected_version":0}' \
|
|
127.0.0.1:50051 kvrpc.KvCas/CompareAndSwap
|
|
grpcurl -plaintext -d '{"namespace":"default","key":"a"}' \
|
|
127.0.0.1:50051 kvrpc.KvCas/Get
|
|
```
|
|
|
|
## Ops checklist
|
|
|
|
- Use `ListNamespaceModes` to confirm all nodes share the same mode set before traffic.
|
|
- Apply mode updates namespace-by-namespace on each node (or automate via PD) until `from_default=false` everywhere for configured namespaces.
|
|
- Keep the default namespace as strong unless explicitly relaxed.
|
|
|
|
## Verification
|
|
|
|
Run the hardened verify script before committing:
|
|
|
|
```bash
|
|
scripts/verify-raft.sh
|
|
# Expected: cargo fmt clean, all rdb-server tests pass (strong/eventual mode flows)
|
|
```
|
|
|
|
This executes `cargo fmt` and `cargo test -p rdb-server --tests` in the Nix shell with protobuf/libclang prepared.
|