docs: v1.3.0 raft-supported docs, limitations, runbook updates
This commit is contained in:
+13
-2
@@ -5,7 +5,7 @@ BaraDB поддържа разпределено внедряване с Raft к
|
||||
> ⚠️ **Ограничение при множество бази данни**
|
||||
> Разпределените модули (Raft, шардиране и репликация) в момента работят само с **`default`** базата данни. Ако използвате множество бази (`CREATE DATABASE`, `USE DATABASE`), разпределените функции още не ги обхващат. Всяка база данни се нуждае от отделна кластър конфигурация.
|
||||
|
||||
> **Статус (2026-07-30):** Raft C3a (мрежова election), C3b (SQL записи), DDL репликация, leader forwarding, log compaction и metrics са **на `main`**. Преглед: `docs/superpowers/specs/2026-07-30-raft-cluster-status.md`.
|
||||
> **Статус (2026-07-30, v1.3.0):** Raft е **supported** за обхвата single-`default`-DB: failover под товар, raft TLS и cold-node recovery чрез InstallSnapshot са e2e-доказани. Преглед: `docs/superpowers/specs/2026-07-30-raft-cluster-status.md`.
|
||||
|
||||
## Raft Консенсус
|
||||
|
||||
@@ -20,10 +20,21 @@ Leader election и log репликация през TCP; SQL DML/DDL за **def
|
||||
| `BARADB_RAFT_WRITE_TIMEOUT_MS` | Макс. изчакване за majority commit при SQL записи (по подразбиране 5000) |
|
||||
| `BARADB_RAFT_CLIENT_PEERS` | Опционален `id@host:clientPort` map за leader write forwarding |
|
||||
| `BARADB_RAFT_LOG_MAX_ENTRIES` | Лимит на in-memory raft log (по подразбиране 256); safe prefix compact |
|
||||
| `BARADB_RAFT_SNAP_CHUNK_KB` | Размер на InstallSnapshot chunk в KiB (по подразбиране 256) |
|
||||
| `BARADB_RAFT_PEER_STALE_MS` | Peer е „stale“ след толкова ms без ack (по подразбиране 30000); stale peers не блокират compaction |
|
||||
| `BARADB_RAFT_TLS_ENABLED` | TLS на raft порта (по подразбиране false; стартът спира при липсващ cert/key) |
|
||||
| `BARADB_RAFT_TLS_CERT_FILE` / `BARADB_RAFT_TLS_KEY_FILE` | Сертификат и ключ за raft listener-а |
|
||||
| `BARADB_RAFT_TLS_CA_FILE` / `BARADB_RAFT_TLS_VERIFY_PEER` | Опционален CA bundle и mutual auth (по подразбиране false) |
|
||||
|
||||
Когато Raft е активен, SQL DML и schema DDL се приемат само от лидера на **`default`**. DML отива като put/delete; DDL — като `ddl` запис. Followers **препращат** write/DDL към лидера, ако е зададен `BARADB_RAFT_CLIENT_PEERS`; иначе връщат `not leader; leader is '…'`. Записи към друга database name се отказват. `CREATE`/`DROP DATABASE` не се репликират. Приложен DML обновява и secondary индекси/графи.
|
||||
|
||||
**Log compaction (v1):** след apply node-ът може да изреже safe prefix, когато log-ът надхвърли `BARADB_RAFT_LOG_MAX_ENTRIES`. Leader не реже след matchIndex на peer (catch-up с AppendEntries). Snapshot metadata се пази в `raft_state.bin`.
|
||||
**Log compaction:** след apply node-ът може да изреже safe prefix, когато log-ът надхвърли `BARADB_RAFT_LOG_MAX_ENTRIES`. На лидера safe prefix се смята само по peers с ack в рамките на `BARADB_RAFT_PEER_STALE_MS`; stale peers се възстановяват със snapshot при завръщане. Snapshot metadata се пази в `raft_state.bin`.
|
||||
|
||||
**Snapshot recovery (InstallSnapshot, v1.3.0):** когато изоставането на follower е невъзстановимо, лидерът изпраща `tar.gz` snapshot на default DB на chunk-ове от `BARADB_RAFT_SNAP_CHUNK_KB` KiB. Follower-ът го възстановява през backup/restore пътя и продължава catch-up. Върнат след дълъг прекъсване или **изтрит** (wiped data dir, същото node id) възел конвергира автоматично. E2E: `tests/raft_coldnode_e2e_test.nim`.
|
||||
|
||||
**Клиентски договор при failover:** запис, който е in-flight при смяна на лидера, **гърми бързо с грешка** — клиентът трябва да го повтори (retry). Всеки **потвърден** (acknowledged) запис оцелява failover-а и е наличен на новия лидер и на наваксалите followers. E2E: `tests/raft_failover_load_e2e_test.nim`.
|
||||
|
||||
**Raft TLS (v1.3.0):** `BARADB_RAFT_TLS_ENABLED=true` + cert/key на всеки възел; стартът спира при липсващ cert/key. Целият клъстер трябва да е в един и същ режим — plaintext възел не може да говори с TLS порт и е изключен от клъстера (`tests/raft_tls_e2e_test.nim`). Forwarding-ът follower→leader се обвива в TLS, когато клиентският wire порт е с TLS.
|
||||
|
||||
**Metrics:** при включен raft `GET /metrics` (HTTP = `BARADB_PORT + 440`) дава Prometheus редове: `baradb_raft_is_leader`, `baradb_raft_term`, `baradb_raft_log_entries`, `baradb_raft_apply_lag`, `baradb_raft_commit_wait_ms_total`, `baradb_raft_elections_total`, `baradb_raft_forwards_total`, `baradb_raft_compactions_total`. `GET /health` включва обект `raft` (`role`, `term`, `leader_id`, …).
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Известни ограничения — v1.2.0 Production GA
|
||||
# Известни ограничения — v1.3.0
|
||||
|
||||
| Ниво | Значение |
|
||||
|------|----------|
|
||||
@@ -8,25 +8,33 @@
|
||||
|
||||
## Матрица
|
||||
|
||||
| Област | GA (v1.2.0) | Experimental / по-късно |
|
||||
|--------|-------------|-------------------------|
|
||||
| Област | v1.3.0 | Experimental / по-късно |
|
||||
|--------|--------|-------------------------|
|
||||
| Single-node SQL + LSM | **Supported** | — |
|
||||
| Schema / FTS / HNSW / graphs persist | **Supported** | — |
|
||||
| Auth + JWT (когато е конфигуриран) | **Supported** | — |
|
||||
| Backup / restore | **Supported** | — |
|
||||
| Multi-DB (без Raft) | **Supported** | — |
|
||||
| Raft 3-node + SQL/DDL | **Experimental** | InstallSnapshot, membership |
|
||||
| Raft 3-node (само `default` DB) | **Supported** | failover под товар, TLS, InstallSnapshot — e2e |
|
||||
| Raft multi-DB | **Not supported** | само `default` |
|
||||
| `CREATE`/`DROP DATABASE` репликация | **Not supported** | per node |
|
||||
| Raft membership промени (join/leave) | **Not supported** | фиксиран `BARADB_RAFT_PEERS` |
|
||||
| Follower linearizable reads | **Not supported** | best-effort след apply |
|
||||
| Rolling upgrades | **Not supported** | рестарт на всички възли заедно — смесени v1.2/v1.3 binaries не трябва да работят в един клъстер |
|
||||
| ORC multi-thread shared LSM | **Not supported** | ARC по подразбиране |
|
||||
|
||||
## GA (single-node)
|
||||
|
||||
Crash recovery с WAL, schema/index persist, `/health` + `/metrics`, offline backup/restore.
|
||||
|
||||
## Raft
|
||||
## Raft (supported)
|
||||
|
||||
Виж [distributed.md](distributed.md). Staging/ops, **не** v1.2.0 HA продукт.
|
||||
Виж [distributed.md](distributed.md). Поддържан обхват: 3-node, DML/DDL само върху `default`, failover под товар (acked writes оцеляват; in-flight writes → грешка, retry), raft TLS, cold-node recovery чрез InstallSnapshot.
|
||||
|
||||
## Нови ограничения
|
||||
|
||||
- **Legacy REP replication (без raft)** — пътят още извежда delete от празна стойност; insert в PK-only таблица се прилага грешно по него (редът изчезва). Използвай raft.
|
||||
- **Snapshot-restore ctx** — след InstallSnapshot restore HTTP endpoints със startup-captured ctx може да сервират стари данни до рестарт (`/query` е свеж per-request); съществуващите клиентски връзки виждат pre-restore състояние — reconnect след restore.
|
||||
|
||||
## Виж също
|
||||
|
||||
|
||||
Reference in New Issue
Block a user