baraba/Baradb
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand README and documentation for production release

Browse Source 
- Update README.md status from 'educational proof-of-concept' to 'production-ready'
- Fix binary size: 286KB -> 3.3MB
- Update test count: 162/35 -> 262/56
- Add sections: benchmarks, Docker, clients, security, config, monitoring, backup, cross-modal queries, troubleshooting
- Expand project structure with all 49 modules and ~14,100 LOC
- Add 10 new docs: performance, deployment, configuration, clients, security, monitoring, backup, crossmodal, troubleshooting, changelog
- Expand docs/en: architecture, baraql, installation, protocol
- Update docs/bg: architecture, installation
- Update docs/index.md with new links
- Update .gitignore for __pycache__, rust/target, nim binaries
This commit is contained in:
dimgigov
2026-05-06 17:19:16 +03:00
parent e1bae0c7a0
commit 8993cdc6f3
20 changed files with 4162 additions and 277 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/bg/architecture.md
+95 -33
View File
@@ -11,17 +11,17 @@ BaraDB е **мултимодална база данни** написана на
│ 1. СЛОЙ ЗА КЛИЕНТИ │
│ Binary Protocol │ HTTP/REST │ WebSocket │ Embedded │
├─────────────────────────────────────────────────────────┤
│ 2. ЗАЯВКИ СЛОЙ (BaraQL) │
│ Lexer → Parser → AST → IR → Optimizer → Codegen │
│ 2. ЗАЯВКИ СЛОЙ (BaraQL) │
│ Lexer → Parser → AST → IR → Optimizer → Codegen │
├─────────────────────────────────────────────────────────┤
│ 3. ИЗПЪЛНИТЕЛЕН ДВИГАТЕЛ │
│ Document │ Graph │ Vector │ Columnar │ FTS │
│ Document │ Graph │ Vector │ Columnar │ FTS │
├─────────────────────────────────────────────────────────┤
│ 4. СЪХРАНЕНИЕ │
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
│ 4. СЪХРАНЕНИЕ │
│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │
├─────────────────────────────────────────────────────────┤
│ 5. РАЗПРЕДЕЛЕНО │
│ Raft Consensus │ Sharding │ Replication │ Gossip │
│ 5. РАЗПРЕДЕЛЕНО │
│ Raft Consensus │ Sharding │ Replication │ Gossip │
└─────────────────────────────────────────────────────────┘
```
@@ -29,50 +29,112 @@ BaraDB е **мултимодална база данни** написана на
Множество протоколи за комуникация:
- **Binary Protocol**: Ефективен протокол с 16 типа съобщения
- **HTTP/REST**: JSON-basiran REST API
- **WebSocket**: Пълен дуплекс стрийминг
- **Embedded**: Директен достъп в процеса
- **Binary Protocol** (`protocol/wire.nim`): Ефективен big-endian бинарен протокол с 16 типа съобщения
- **HTTP/REST** (`core/httpserver.nim`): JSON REST API с мулти-трединг
- **WebSocket** (`core/websocket.nim`): Пълен дуплекс стрийминг
- **Embedded** (`storage/lsm.nim`): Директен in-process достъп
### Управление на Връзките
- **Connection Pool** (`protocol/pool.nim`): Мин/макс лимити на връзки
- **Rate Limiting** (`protocol/ratelimit.nim`): Token-bucket лимитиране
- **Authentication** (`protocol/auth.nim`): JWT с HMAC-SHA256
- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с авто-генерирани сертификати
## Слой 2: Заявки (BaraQL)
Pipeline-а на BaraQL:
1. **Lexer**: Токенизира входа в 80+ типа токени
2. **Parser**: Рекурсивен descent парсър произвеждащ AST
3. **AST**: 300+ реда покриващи 25+ вида възли
4. **IR**: Междинно представяне за планове за изпълнение
5. **Optimizer/Codegen**: Транслира IR към операции върху съхранение
1. **Lexer** (`query/lexer.nim`): Токенизира входа в 80+ типа токени
2. **Parser** (`query/parser.nim`): Рекурсивен descent парсър произвеждащ AST
3. **AST** (`query/ast.nim`): 300+ реда покриващи 25+ вида възли
4. **IR** (`query/ir.nim`): Междинно представяне за планове за изпълнение
5. **Optimizer** (`query/adaptive.nim`): Адаптивен крос-модален оптимизатор
6. **Codegen** (`query/codegen.nim`): Транслира IR към операции върху съхранение
7. **Executor** (`query/executor.nim`): Изпълнява планове с паралелизация
### Крос-Модално Планиране
Оптимизаторът определя реда на изпълнение между двигателите:
```
1. Оценка на селективност за всеки предикат
2. Най-селективният предикат се изпълнява първи
3. Bloom филтри за KV търсения
4. Паралелизация на независими клонове
```
## Слой 3: Изпълнителен Двигател
### Document/KV Двигател
- **LSM-Tree**: Оптимизиран за запис
- **B-Tree Index**: Подреден индекс за диапазони
- **LSM-Tree** (`storage/lsm.nim`): Оптимизиран за запис с MemTable, WAL, SSTables
- **B-Tree Index** (`storage/btree.nim`): Подреден индекс за диапазони с COW
### Vector Engine
- **HNSW**: Иерархичен навигируем малък свят
- **IVF-PQ**: Инвертиран файл с продуктово квантуване
- **SIMD**: Ускорени разстояния
- **HNSW** (`vector/engine.nim`): Иерархичен навигируем малък свят
- **IVF-PQ** (`vector/engine.nim`): Инвертиран файл с продуктово квантуване
- **SIMD** (`vector/simd.nim`): AVX2-оптимизирани изчисления на разстояния
- **Quantization** (`vector/quant.nim`): Скаларно, продуктово и бинарно квантуване
### Graph Engine
- **Списък със съседи**: Насочен граф с тегла
- **Алгоритми**: BFS, DFS, Dijkstra, PageRank, Louvain
- **Списък със съседи** (`graph/engine.nim`): Насочен граф с тегла
- **Алгоритми** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank
- **Community Detection** (`graph/community.nim`): Louvain алгоритъм
- **Pattern Matching** (`graph/community.nim`): Subgraph isomorphism
- **Cypher Parser** (`graph/cypher.nim`): Cypher-подобни заявки
### FTS
- **Инвертиран индекс**: Термин-документ индекс
- **Ранжиране**: BM25 и TF-IDF
- **Многоезичен**: Токенизация за EN, BG, DE, FR, RU
- **Инвертиран индекс** (`fts/engine.nim`): Термин-документ индекс
- **Ранжиране** (`fts/engine.nim`): BM25 и TF-IDF
- **Fuzzy Search** (`fts/engine.nim`): Levenshtein разстояние
- **Многоезичен** (`fts/multilang.nim`): Токенизация за EN, BG, DE, FR, RU
### Columnar Engine
- **Колонно съхранение** (`core/columnar.nim`): Аналитични заявки
- **Компресия**: RLE и dictionary encoding
- **SIMD агрегати**: Ускорени агрегатни функции
## Слой 4: Съхранение
- **LSM-Tree**: MemTable, WAL, SSTable, Bloom Filter, Compaction
- **Page Cache**: LRU кеш
- **Memory-mapped I/O**: mmap-базиран достъп
- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom Filter, Compaction
- **Page Cache** (`storage/compaction.nim`): LRU кеш
- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-базиран достъп
- **Recovery** (`storage/recovery.nim`): WAL replay и възстановяване
### Път на Запис
```
Client → Protocol → Auth → Parser → AST → IR → Codegen
→ StorageOp → MVCC Txn → WAL Write → MemTable → Commit
```
### Път на Четене
```
Client → Protocol → Auth → Parser → AST → IR → Codegen
→ StorageOp → MVCC Snapshot → MemTable → SSTable → Result
```
## Слой 5: Разпределено
- **Raft Consensus**: Лидерско избиране, репликация на логове
- **Sharding**: Hash, range и консистентно хеширане
- **Replication**: Sync, async, semi-sync режими
- **Gossip Protocol**: Управление на членство
- **Raft Consensus** (`core/raft.nim`): Лидерско избиране, репликация на логове
- **Sharding** (`core/sharding.nim`): Hash, range и консистентно хеширане
- **Replication** (`core/replication.nim`): Sync, async, semi-sync режими
- **Gossip Protocol** (`core/gossip.nim`): SWIM-подобно управление на членство
- **Distributed Transactions** (`core/disttxn.nim`): Two-phase commit
## Статистика на Модулите
| Категория | Модули | Редове Код | Предназначение |
|-----------|--------|------------|----------------|
| Core | 16 | ~4,200 | Сървър, протоколи, транзакции, разпределено |
| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, compaction, mmap |
| Query | 7 | ~2,800 | Lexer, parser, AST, IR, оптимизатор, codegen, executor |
| Vector | 3 | ~1,200 | HNSW, IVF-PQ, квантуване, SIMD |
| Graph | 3 | ~1,000 | Списък със съседи, алгоритми, community detection |
| FTS | 2 | ~900 | Инвертиран индекс, BM25, fuzzy, многоезичен |
| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, pool, auth, rate limit, SSL |
| Schema | 1 | ~600 | Типове, връзки, наследяване, миграции |
| Client | 2 | ~800 | Nim binary client, file helpers |
| CLI | 1 | ~400 | Интерактивна BaraQL конзола |
| **Общо** | **49** | **~14,100** | |
docs/bg/installation.md
+141 -29
View File
@@ -2,33 +2,85 @@
## Изисквания
- **Nim Компилатор** >= 2.0.0
- **Nim Компилатор** >= 2.2.0
- **OpenSSL** development headers (за TLS поддръжка)
- **Операционна система**: Linux, macOS, Windows
### Поддържани Платформи
| ОС | Архитектура | Статус |
|----|-------------|--------|
| Linux | x86_64 | ✅ Пълна поддръжка |
| Linux | ARM64 | ✅ Пълна поддръжка |
| macOS | x86_64 | ✅ Пълна поддръжка |
| macOS | ARM64 (Apple Silicon) | ✅ Пълна поддръжка |
| Windows | x86_64 | ✅ Поддръжка |
## Инсталиране на Nim
### Linux/macOS
### Linux
```bash
# Официален инсталатор
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install nim
# Fedora
sudo dnf install nim
# Arch Linux
sudo pacman -S nim
```
Или чрез пакетен мениджър:
### macOS
```bash
# Ubuntu/Debian
apt-get install nim
# macOS
# Homebrew
brew install nim
# MacPorts
sudo port install nim
```
### Windows
Изтеглете инсталатора от [nim-lang.org](https://nim-lang.org/install.html) или използвайте winget:
```powershell
# Winget
winget install nim
# Scoop
scoop install nim
```
### Проверка
```bash
nim --version
# Очакван резултат: Nim Compiler Version 2.2.0 или по-нова
```
## Инсталиране на OpenSSL
### Linux
```bash
# Ubuntu/Debian
sudo apt-get install libssl-dev
# Fedora
sudo dnf install openssl-devel
# Arch Linux
sudo pacman -S openssl
```
### macOS
```bash
brew install openssl
```
## Компилиране на BaraDB
@@ -40,57 +92,117 @@ git clone https://github.com/katehonz/barabaDB.git
cd barabaDB
```
### Компилиране
### Инсталиране на Зависимости
```bash
# Debug компилация
nim c -o:build/baradadb src/baradadb.nim
# Release компилация (оптимизирана)
nim c -d:release -o:build/baradadb src/baradadb.nim
nimble install -d -y
```
### Стартиране на Тестове
### Опции за Компилация
#### Debug Компилация
```bash
nim c --path:src -r tests/test_all.nim
nim c -d:ssl -o:build/baradadb src/baradadb.nim
```
### Стартиране на Бенчмаркове
#### Release Компилация (Препоръчителна)
```bash
nim c -d:release -r benchmarks/bench_all.nim
nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim
```
#### Използване на Nimble
```bash
nimble build_debug
nimble build_release
```
#### Минимален Размер
```bash
nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
strip build/baradadb
```
### Проверка на Компилацията
```bash
./build/baradadb --version
# Очакван резултат: BaraDB v0.1.0 — Multimodal Database Engine
```
## Стартиране на Тестове
```bash
# Всички тестове (262 теста, 56 сюита)
nim c -d:ssl -r tests/test_all.nim
# Бенчмаркове
nim c -d:ssl -d:release -r benchmarks/bench_all.nim
```
## Опции за Инсталация
### Системна Инсталация
```bash
nimble build_release
sudo cp build/baradadb /usr/local/bin/
sudo chmod +x /usr/local/bin/baradadb
sudo mkdir -p /var/lib/baradb
```
### Docker
```bash
docker pull barabadb/barabadb
docker run -it barabadb/barabadb
docker pull barabadb/barabadb:latest
docker run -d \
-p 5432:5432 \
-p 8080:8080 \
-p 8081:8081 \
-v baradb_data:/data \
barabadb/barabadb
```
### Docker Compose
```bash
docker-compose up -d
```
### Вградено Използване
Добавете към вашия `.nimble` файл:
```nim
requires "barabadb >= 1.0.0"
requires "barabadb >= 0.1.0"
```
След това импортнете в кода:
```nim
import barabadb
import barabadb/storage/lsm
var db = newLSMTree("./data")
db.put("key1", cast[seq[byte]]("value1"))
db.put("key", cast[seq[byte]]("value"))
let (found, val) = db.get("key")
db.close()
```
## Първо Стартиране
```bash
# Стартиране на сървъра
./build/baradadb
# Тестване на HTTP API
curl http://localhost:8080/health
# Интерактивна конзола
./build/baradadb --shell
```
## Следващи Стъпки
- [Бързо Стартиране](bg/quickstart.md)
- [Конфигурация](en/configuration.md)
- [Архитектура](bg/architecture.md)
- [BaraQL Заявки](bg/baraql.md)
- [BaraQL Заявки](bg/baraql.md)