diff --git a/docs/ar/mcp.md b/docs/ar/mcp.md new file mode 100644 index 0000000..d041d64 --- /dev/null +++ b/docs/ar/mcp.md @@ -0,0 +1,109 @@ +# خادم MCP (Model Context Protocol) + +يتضمن BaraDB خادم MCP مدمج يمكّن وكلاء الذكاء الاصطناعي (Claude و Cursor وما إلى ذلك) من التفاعل مع قاعدة البيانات مباشرة. + +## البداية السريعة + +```bash +./build/baramcp --data-dir ./data +``` + +يبدأ في وضع STDIO، يقبل رسائل JSON-RPC 2.0 على stdin. + +## الأدوات المتاحة + +### 1. `query` — تنفيذ SQL + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +استعلامات معاملية باستخدام `?` placeholders. دعم multi-tenant عبر `tenant_id` و `user_id`. + +### 2. `vector_search` — البحث الدلالي + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +المقاييس: `cosine`، `euclidean`، `dot_product`، `manhattan`. + +### 3. `schema_inspect` — استكشاف المخطط + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +إرجاع الجداول والأعمدة والأنواع والمفاتيح الأساسية والمفاتيح الخارجية والفهارس وسياسات RLS. + +## تكوين Claude Desktop + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## تكوين Cursor + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## عزل Multi-Tenant + +يمكن أن يتضمن كل طلب MCP قيمة `tenant_id` و `user_id`، والتي يتم تعيينها كمتغيرات جلسة: +- `app.tenant_id` — للترشيح RLS +- `app.user_id` — لمراجع `current_user` + +تقوم سياسات RLS بتصفية البيانات تلقائياً بناءً على هذه المتغيرات. + +## بروتوكول JSON-RPC 2.0 + +يستخدم الخادم JSON-RPC 2.0 عبر STDIO: + +```json +// الطلب +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// الاستجابة +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +``` diff --git a/docs/bg/index.md b/docs/bg/index.md new file mode 100644 index 0000000..78bbd5a --- /dev/null +++ b/docs/bg/index.md @@ -0,0 +1,64 @@ +# BaraDB Документация + +**Мултимодална система за управление на бази данни — 100% Nim, без външни зависимости.** + +## Езици + +- [English](../en/) +- [Български (Bulgarian)](../bg/) +- [Deutsch (German)](../de/) +- [Русский (Russian)](../ru/) +- [فارسی (Farsi)](../fa/) +- [中文 (Chinese)](../zh/) +- [Türkçe (Turkish)](../tr/) +- [العربية (Arabic)](../ar/) + +--- + +## Бързо Стартиране + +- [Инсталация](installation.md) +- [Бързо Стартиране](quickstart.md) +- [Архитектура](architecture.md) +- [Конфигурация](configuration.md) + +## Основни Концепции + +- [BaraQL Език за Заявки](baraql.md) +- [Системи за Съхранение](storage.md) +- [Схема Система](schema.md) + +## Двигатели + +- [LSM-Tree Съхранение](lsm.md) +- [B-Tree Индекс](btree.md) +- [Векторно Търсене](vector.md) +- [Графов Двигател](graph.md) +- [Пълнотекстово Търсене](fts.md) +- [Колоночно Съхранение](columnar.md) + +## API & Клиенти + +- [Client SDKs](clients.md) +- [Бинарен Протокол](api-binary.md) +- [HTTP/REST API](api-http.md) +- [MCP Сървър](mcp.md) + +## Операции + +- [Производителност](performance.md) +- [Сигурност](security.md) +- [Мониторинг](monitoring.md) +- [Архивиране и Възстановяване](backup.md) +- [Отстраняване на Проблеми](troubleshooting.md) + +## Разширени + +- [Транзакции и MVCC](transactions.md) +- [Разпределени Системи](distributed.md) +- [Docker Deployment](docker.md) +- [Дневник на Промените](changelog.md) + +--- + +*За да добавите нов език, създайте нова папка в `docs/` с езиковия код (напр. `docs/de/`).* diff --git a/docs/bg/mcp.md b/docs/bg/mcp.md new file mode 100644 index 0000000..1093c0f --- /dev/null +++ b/docs/bg/mcp.md @@ -0,0 +1,109 @@ +# MCP Сървър (Model Context Protocol) + +BaraDB включва вграден MCP сървър, който позволява на AI агенти (Claude, Cursor и др.) да взаимодействат директно с базата данни. + +## Бързо Стартиране + +```bash +./build/baramcp --data-dir ./data +``` + +Стартира в STDIO режим, приемащ JSON-RPC 2.0 съобщения на stdin. + +## Налични Инструменти + +### 1. `query` — Изпълнение на SQL + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +Параметризирани заявки с `?` placeholders. Multi-tenant поддръжка чрез `tenant_id` и `user_id`. + +### 2. `vector_search` — Семантично Търсене + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +Метрики: `cosine`, `euclidean`, `dot_product`, `manhattan`. + +### 3. `schema_inspect` — Изследване на Схемата + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +Връща таблици, колони, типове, първични ключове, външни ключове, индекси и RLS политики. + +## Конфигурация в Claude Desktop + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## Конфигурация в Cursor + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## Multi-Tenant Изолация + +Всяка MCP заявка може да включва `tenant_id` и `user_id`, зададени като session variables: +- `app.tenant_id` — за RLS филтриране +- `app.user_id` — за `current_user` референции + +RLS политиките автоматично филтрират данните въз основа на тези променливи. + +## JSON-RPC 2.0 Протокол + +Сървърът използва JSON-RPC 2.0 през STDIO: + +```json +// Заявка +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// Отговор +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +``` diff --git a/docs/de/api-binary.md b/docs/de/api-binary.md new file mode 100644 index 0000000..142424c --- /dev/null +++ b/docs/de/api-binary.md @@ -0,0 +1,74 @@ +# Binärprotokoll API + +Niedrigstufiges Wire-Protokoll für hochperformante Client-Verbindungen. + +## Nachrichtenformat + +Alle Nachrichten verwenden Big-Endian-Byte-Reihenfolge: + +``` +┌────────┬────────┬────────┬────────┬─────────────┐ +│ Length │ Type │ Seq │ Status │ Payload │ +│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ +└────────┴────────┴────────┴────────┴─────────────┘ +``` + +## Nachrichtentypen + +### Query (0x01) + +```nim +let msg = makeQueryMessage(seq, "SELECT * FROM users") +``` + +### Insert (0x02) + +```nim +let msg = makeInsertMessage(seq, "users", data) +``` + +### Update (0x03) + +```nim +let msg = makeUpdateMessage(seq, "users", updates, where) +``` + +### Delete (0x04) + +```nim +let msg = makeDeleteMessage(seq, "users", where) +``` + +### Ready (0x05) + +```nim +let msg = makeReadyMessage(seq) +``` + +### Error (0x06) + +```nim +let msg = makeErrorMessage(seq, code, message) +``` + +## Antwortcodes + +| Code | Name | Beschreibung | +|------|------|-------------| +| 0x00 | OK | Erfolg | +| 0x01 | ERROR | Allgemeiner Fehler | +| 0x02 | AUTH_REQUIRED | Authentifizierung erforderlich | +| 0x03 | INVALID_QUERY | Abfragesyntaxfehler | +| 0x04 | NOT_FOUND | Ressource nicht gefunden | + +## Serialisierung + +```nim +import barabadb/protocol/wire + +# Wert serialisieren +let bytes = serializeValue(Value(kind: vkString, strVal: "test")) + +# Wert deserialisieren +let value = deserializeValue(bytes) +``` diff --git a/docs/de/api-http.md b/docs/de/api-http.md new file mode 100644 index 0000000..f6fac80 --- /dev/null +++ b/docs/de/api-http.md @@ -0,0 +1,91 @@ +# HTTP/REST API + +JSON-basierte REST API für Web-Anwendungen. + +## Basis-URL + +``` +http://localhost:9470/api +``` + +## Endpoints + +### GET /api/users + +Alle Benutzer auflisten: + +```bash +curl http://localhost:9470/api/users +``` + +Antwort: +```json +[ + {"id": 1, "name": "Alice", "age": 30}, + {"id": 2, "name": "Bob", "age": 25} +] +``` + +### GET /api/users/:id + +Benutzer nach ID abrufen: + +```bash +curl http://localhost:9470/api/users/1 +``` + +### POST /api/users + +Benutzer erstellen: + +```bash +curl -X POST http://localhost:9470/api/users \ + -H "Content-Type: application/json" \ + -d '{"name": "Charlie", "age": 35}' +``` + +### PUT /api/users/:id + +Benutzer aktualisieren: + +```bash +curl -X PUT http://localhost:9470/api/users/1 \ + -H "Content-Type: application/json" \ + -d '{"name": "Alice", "age": 31}' +``` + +### DELETE /api/users/:id + +Benutzer löschen: + +```bash +curl -X DELETE http://localhost:9470/api/users/1 +``` + +## Query-Endpoint + +BaraQL-Abfragen über HTTP ausführen: + +```bash +curl -X POST http://localhost:9470/api/query \ + -H "Content-Type: application/json" \ + -d '{"sql": "SELECT * FROM users WHERE age > 18"}' +``` + +## Fehlerantwort + +```json +{ + "error": { + "code": "INVALID_QUERY", + "message": "Syntax error at line 1" + } +} +``` + +## Authentifizierung + +```bash +curl -H "Authorization: Bearer " \ + http://localhost:9470/api/users +``` diff --git a/docs/de/api-websocket.md b/docs/de/api-websocket.md new file mode 100644 index 0000000..39562f0 --- /dev/null +++ b/docs/de/api-websocket.md @@ -0,0 +1,120 @@ +# WebSocket API + +Vollduplex-Streaming für Echtzeit-Datenfeeds und Push-Benachrichtigungen. + +## Verbindung + +``` +ws://localhost:9471/ws +``` + +## Client-Beispiel + +```javascript +const ws = new WebSocket('ws://localhost:9471/ws'); + +ws.onopen = () => { + console.log('Connected'); + ws.send(JSON.stringify({ + type: 'query', + sql: 'SELECT * FROM users' + })); +}; + +ws.onmessage = (event) => { + const data = JSON.parse(event.data); + console.log('Received:', data); +}; +``` + +## Nachrichtenformat + +```json +{ + "type": "query", + "id": "uuid", + "sql": "SELECT * FROM users" +} +``` + +## Nachrichtentypen + +### Query-Anfrage + +```json +{ + "type": "query", + "id": "123", + "sql": "SELECT * FROM users" +} +``` + +### Query-Antwort + +```json +{ + "type": "result", + "id": "123", + "data": [ + {"id": 1, "name": "Alice"}, + {"id": 2, "name": "Bob"} + ] +} +``` + +### Fehlerantwort + +```json +{ + "type": "error", + "id": "123", + "error": { + "code": "INVALID_QUERY", + "message": "Syntax error" + } +} +``` + +### Subscription + +Änderungen abonnieren: + +```json +{ + "type": "subscribe", + "id": "sub1", + "table": "users" +} +``` + +### Push-Benachrichtigung + +Server-Push: + +```json +{ + "type": "push", + "table": "users", + "action": "insert", + "data": {"id": 3, "name": "Charlie"} +} +``` + +## JavaScript-Client + +```javascript +class BaraDBClient { + constructor(url) { + this.ws = new WebSocket(url); + this.pending = new Map(); + } + + query(sql) { + return new Promise((resolve, reject) => { + const id = crypto.randomUUID(); + this.pending.set(id, { resolve, reject }); + this.ws.send(JSON.stringify({ type: 'query', id, sql })); + }); + } +} +``` diff --git a/docs/de/architecture.md b/docs/de/architecture.md new file mode 100644 index 0000000..5717735 --- /dev/null +++ b/docs/de/architecture.md @@ -0,0 +1,152 @@ +# BaraDB Architektur + +## Überblick + +BaraDB ist eine **multimodale Datenbank-Engine** in Nim, die Document (KV), Graph, Vector, Columnar und Full-Text Search Speicherung in einer einzigen Engine mit einer einheitlichen Abfragesprache namens **BaraQL** kombiniert. + +## Schichten-Architektur + +``` +┌─────────────────────────────────────────────────────────┐ +│ 1. CLIENT LAYER │ +│ Binary Protocol │ HTTP/REST │ WebSocket │ Embedded │ +├─────────────────────────────────────────────────────────┤ +│ 2. QUERY LAYER (BaraQL) │ +│ Lexer → Parser → AST → IR → Optimizer → Codegen │ +├─────────────────────────────────────────────────────────┤ +│ 3. EXECUTION ENGINE │ +│ Document │ Graph │ Vector │ Columnar │ FTS │ +├─────────────────────────────────────────────────────────┤ +│ 4. STORAGE │ +│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Compaction │ Cache │ +├─────────────────────────────────────────────────────────┤ +│ 5. DISTRIBUTED │ +│ Raft Consensus │ Sharding │ Replication │ Gossip │ +└─────────────────────────────────────────────────────────┘ +``` + +## Schicht 1: Client-Layer + +Mehrere Kommunikationsprotokolle: + +- **Binärprotokoll** (`protocol/wire.nim`): Effizientes Big-Endian Binärprotokoll mit 16 Nachrichtentypen +- **HTTP/REST** (`core/httpserver.nim`): JSON-basierte REST API mit Multi-Threading +- **WebSocket** (`core/websocket.nim`): Vollduplex-Streaming +- **Embedded** (`storage/lsm.nim`): Direkter In-Process-Zugriff + +### Verbindungsmanagement + +- **Connection Pool** (`protocol/pool.nim`): Min/Max Verbindungslimits mit Idle-Timeout +- **Rate Limiting** (`protocol/ratelimit.nim`): Token-Bucket globale und per-Client Limits +- **Authentifizierung** (`protocol/auth.nim`): JWT mit HMAC-SHA256 und rollenbasierter Zugriff +- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 mit auto-generierten Zertifikaten + +## Schicht 2: Query-Layer (BaraQL) + +Die BaraQL-Pipeline: + +1. **Lexer** (`query/lexer.nim`): Tokenisiert Eingabe in 80+ Tokentypen +2. **Parser** (`query/parser.nim`): Rekursiver Descent-Parser produziert AST +3. **AST** (`query/ast.nim`): 300+ Zeilen mit 25+ Knotenarten +4. **IR** (`query/ir.nim`): Intermediate Representation für Ausführungspläne +5. **Optimizer** (`query/adaptive.nim`): Adaptive Cross-Modal Query-Optimierung +6. **Codegen** (`query/codegen.nim`): Übersetzt IR zu Speicheroperationen +7. **Executor** (`query/executor.nim`): Führt Pläne mit Parallelisierung aus + +### Cross-Modal Planning + +Der Optimizer (`query/adaptive.nim`) bestimmt die Ausführungsreihenfolge über Engines: + +``` +1. Selektivität für jedes Prädikat schätzen +2. Selektivstes Prädikat zuerst an seine Engine pushen +3. Bloom-Filter für KV-Lookups verwenden +4. Unabhängige Zweige parallelisieren +5. Results streamen um Materialisierung zu vermeiden +``` + +## Schicht 3: Execution Engine + +### Document/KV Engine +- **LSM-Tree** (`storage/lsm.nim`): Write-optimierte Speicherung mit MemTable, WAL, SSTables +- **B-Tree Index** (`storage/btree.nim`): Geordneter Index für Bereichsscans mit COW + +### Vector Engine (`vector/`) +- **HNSW Index** (`vector/engine.nim`): Hierarchical Navigable Small World Graph +- **IVF-PQ Index** (`vector/engine.nim`): Inverted File Index mit Product Quantization +- **SIMD Operations** (`vector/simd.nim`): AVX2-optimierte Distanzberechnungen +- **Quantization** (`vector/quant.nim`): Scalar, Product und Binary Quantization + +### Graph Engine (`graph/`) +- **Adjacency List** (`graph/engine.nim`): Kanten-gewichteter gerichteter Graph +- **Algorithmen** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank +- **Community Detection** (`graph/community.nim`): Louvain-Algorithmus +- **Pattern Matching** (`graph/community.nim`): Subgraph-Isomorphie +- **Cypher Parser** (`graph/cypher.nim`): Cypher-ähnliche Graph-Abfragen + +### Full-Text Search (`fts/`) +- **Inverted Index** (`fts/engine.nim`): Term-Document Index +- **Ranking** (`fts/engine.nim`): BM25 und TF-IDF Scoring +- **Fuzzy Search** (`fts/engine.nim`): Levenshtein-Distanz-Matching +- **Multi-Language** (`fts/multilang.nim`): Tokenizer für EN, BG, DE, FR, RU + +### Columnar Engine (`core/columnar.nim`) +- Perspalten-Speicherung für analytische Abfragen +- RLE und Dictionary-Kodierung +- SIMD-beschleunigte Aggregatfunktionen + +## Schicht 4: Storage + +- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom-Filter, Compaction +- **Page Cache** (`storage/compaction.nim`): LRU-Cache mit Trefferraten-Verfolgung +- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-basierter Dateizugriff +- **Recovery** (`storage/recovery.nim`): WAL-Replay und Crash-Recovery + +### Write Path + +``` +Client → Protocol → Auth → Parser → AST → IR → Codegen + → StorageOp → MVCC Txn → WAL Write → MemTable → Commit +``` + +### Read Path + +``` +Client → Protocol → Auth → Parser → AST → IR → Codegen + → StorageOp → MVCC Snapshot → MemTable → SSTable → Result +``` + +## Schicht 5: Distributed + +- **Raft Consensus** (`core/raft.nim`): Leader Election, Log-Replikation +- **Sharding** (`core/sharding.nim`): Hash, Range und Consistent Hashing +- **Replication** (`core/replication.nim`): Sync, Async, Semi-Sync Modi +- **Gossip Protocol** (`core/gossip.nim`): SWIM-ähnliches Membership-Management +- **Distributed Transactions** (`core/disttxn.nim`): Two-Phase Commit + +## Wichtige Designentscheidungen + +1. **Reines Nim**: Keine Cython, Python oder Rust Abhängigkeiten +2. **Unified Storage**: Eine Engine-handelt KV, Graph, Vector, FTS und Columnar +3. **Embedded Mode**: Kann als Bibliothek oder Server laufen +4. **Binärprotokoll**: Custom effizientes Wire-Protokoll +5. **MVCC**: Multi-Version Concurrency Control +6. **Schema-First**: Stark typisiertes Schema-System mit Vererbung +7. **Cross-Modal**: Einheitliche Abfragesprache über alle Datenmodelle +8. **Formally Verified**: Kern-Algorithmen in TLA+ spezifiziert und mit TLC model-gecheckt + +## Modulstatistiken + +| Kategorie | Module | Codezeilen | Zweck | +|----------|--------|------------|-------| +| Core | 16 | ~4,200 | Server, Protokolle, Transaktionen, Distributed | +| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, Bloom, Compaction, mmap | +| Query | 7 | ~2,800 | Lexer, Parser, AST, IR, Optimizer, Codegen, Executor | +| Vector | 3 | ~1,200 | HNSW, IVF-PQ, Quantization, SIMD | +| Graph | 3 | ~1,000 | Adjacency List, Algorithmen, Community Detection | +| FTS | 2 | ~900 | Inverted Index, BM25, Fuzzy, Multi-Language | +| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, Pool, Auth, Rate Limit, SSL | +| Schema | 1 | ~600 | Typen, Links, Vererbung, Migrationen | +| Client | 2 | ~800 | Nim Binary Client, File Helpers | +| CLI | 1 | ~400 | Interaktive BaraQL Shell | +| **Total** | **49** | **~14,100** | | diff --git a/docs/de/backup.md b/docs/de/backup.md new file mode 100644 index 0000000..f09a489 --- /dev/null +++ b/docs/de/backup.md @@ -0,0 +1,199 @@ +# Backup & Wiederherstellung + +## Online Snapshots + +BaraDB unterstützt Online-Snapshots ohne Server-Stopp. Der Snapshot erfasst eine +konsistente Point-in-Time-Ansicht mittels MVCC. + +### Snapshot erstellen + +```nim +import barabadb/core/backup + +var bm = newBackupManager() +bm.createSnapshot("/backup/baradb_2025-01-15") +``` + +### Via CLI + +```bash +./build/baradadb --snapshot --output=/backup/snapshot.db +``` + +### Via HTTP API + +```bash +curl -X POST http://localhost:9470/api/backup \ + -H "Content-Type: application/json" \ + -d '{"destination": "/backup/snapshot.db"}' +``` + +### Automatisierte Backups + +Cron für geplante Backups verwenden: + +```bash +# Daily snapshot at 2 AM +0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db + +# Letzte 7 Tage behalten +find /backup -name "baradb_*.db" -mtime +7 -delete +``` + +## Point-in-Time Recovery (PITR) + +BaraDB verwendet das Write-Ahead Log (WAL) für Point-in-Time Recovery. + +### WAL-Archivierung + +Kontinuierliche WAL-Archivierung aktivieren: + +```bash +BARADB_WAL_ARCHIVE_DIR=/backup/wal \ +BARADB_WAL_ARCHIVE_INTERVAL_MS=60000 \ +./build/baradadb +``` + +### Wiederherstellung von Checkpoint + WAL + +```bash +# Von Snapshot wiederherstellen +./build/baradadb --recover \ + --checkpoint=/backup/snapshot.db \ + --wal-dir=/backup/wal + +# Wiederherstellung zu spezifischem LSN +./build/baradadb --recover \ + --checkpoint=/backup/snapshot.db \ + --wal-dir=/backup/wal \ + --target-lsn=15420 + +# Wiederherstellung zu spezifischer Zeit +./build/baradadb --recover \ + --checkpoint=/backup/snapshot.db \ + --wal-dir=/backup/wal \ + --target-time="2025-01-15T10:30:00Z" +``` + +### Wiederherstellung via SQL + +Sie können auch direkt via BaraQL wiederherstellen: + +```sql +RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; +``` + +### Inkrementelle Backups + +Inkrementelle Backups kopieren nur geänderte SSTables: + +```bash +./build/baradadb --backup-incremental \ + --last-backup=/backup/previous \ + --output=/backup/incremental_$(date +%Y%m%d) +``` + +## Replikation als Backup + +Für kontinuierlichen Schutz, Streaming-Replikation verwenden: + +### Primary + +```bash +BARADB_REPLICATION_ENABLED=true \ +BARADB_REPLICATION_MODE=async \ +./build/baradadb +``` + +### Replica + +```bash +BARADB_REPLICATION_ENABLED=true \ +BARADB_REPLICATION_PRIMARY=primary:9472 \ +./build/baradadb +``` + +## Disaster Recovery + +### Wiederherstellungsverfahren + +#### Szenario 1: Einzelne Dateikorruption + +```bash +# Korrupte SSTable aus Logs identifizieren +# Spezifische SSTable aus Backup wiederherstellen +cp /backup/sstables/000012.sst ./data/sstables/ + +# Index neu aufbauen +./build/baradadb --rebuild-index +``` + +#### Szenario 2: Kompletter Datenverlust + +```bash +# 1. Neuesten Snapshot wiederherstellen +cp /backup/snapshot.db ./data/ + +# 2. WAL replay +./build/baradadb --recover --wal-dir=/backup/wal + +# 3. Verifizieren +curl http://localhost:9470/health +``` + +#### Szenario 3: Cluster-Knoten-Ausfall + +```bash +# Für Raft-Cluster, einfach neuen Knoten starten +BARADB_RAFT_NODE_ID=newnode \ +BARADB_RAFT_PEERS=node1:9001,node2:9001 \ +./build/baradadb + +# Der neue Knoten wird über Raft-Log-Replikation aufholen +``` + +## Backup-Verifizierung + +Backups immer verifizieren: + +```bash +# In temporäres Verzeichnis wiederherstellen +./build/baradadb --recover \ + --checkpoint=/backup/snapshot.db \ + --data-dir=/tmp/verify_data + +# Konsistenzprüfung ausführen +curl http://localhost:9470/api/admin/check +``` + +## Speicheranforderungen + +| Backup-Typ | Größe | Häufigkeit | Aufbewahrung | +|-------------|------|-----------|--------------| +| Full snapshot | ~1× Datengröße | Täglich | 7 Tage | +| Inkrementell | ~0.1× Datengröße | Stündlich | 24 Stunden | +| WAL-Archiv | ~0.05× Datengröße / Tag | Kontinuierlich | 30 Tage | + +## Best Practices + +1. **Restores regelmäßig testen** — Ein Backup das Sie nicht wiederherstellen können ist wertlos +2. **Backups außerhalb speichern** — S3, GCS oder Azure Blob verwenden +3. **Backups verschlüsseln** — `gpg` oder OS-Level-Verschlüsselung verwenden +4. **Backup-Jobs überwachen** — Bei fehlgeschlagenen Backups alarmieren +5. **RTO/RPO dokumentieren** — Ihre Wiederherstellungszeit und Punktziele kennen + +### Cloud-Backup-Upload + +```bash +# Zu S3 hochladen +aws s3 cp /backup/snapshot.db s3://my-bucket/baradb/ + +# Zu GCS hochladen +gsutil cp /backup/snapshot.db gs://my-bucket/baradb/ + +# Zu Azure hochladen +az storage blob upload \ + --container-name backups \ + --file /backup/snapshot.db \ + --name baradb/snapshot.db +``` diff --git a/docs/de/btree.md b/docs/de/btree.md new file mode 100644 index 0000000..388155a --- /dev/null +++ b/docs/de/btree.md @@ -0,0 +1,38 @@ +# B-Tree Index + +Geordnete Indexstruktur für effiziente Bereichsabfragen und Point-Lookups. + +## Verwendung + +```nim +import barabadb/storage/btree + +var btree = newBTreeIndex[string, string]() + +# Einfügen +btree.insert("key1", "value1") +btree.insert("key2", "value2") + +# Point-Lookup +let values = btree.get("key1") + +# Bereichsabfrage +let range = btree.scan("key_a", "key_z") + +# Löschen +btree.delete("key1") +``` + +## Funktionen + +- Geordnete Schlüssel-Wert-Speicherung +- Bereichsabfragen (BETWEEN, >, <, >=, <=) +- Präfix-Scans +- Konfigurierbare Seitengröße +- Iterator-Unterstützung + +## Anwendungsfälle + +- Primärschlüssel-Indizes +- Sekundärindizes für häufig abgefragte Spalten +- Bereichspartitionierte Daten diff --git a/docs/de/changelog.md b/docs/de/changelog.md new file mode 100644 index 0000000..00d50c2 --- /dev/null +++ b/docs/de/changelog.md @@ -0,0 +1,247 @@ +# Changelog + +Alle bemerkenswerten Änderungen an BaraDB werden in dieser Datei dokumentiert. + +## [Unreleased] — AI-Native Platform + +### Hinzugefügt + +- **MCP Server (Model Context Protocol)** — STDIO JSON-RPC 2.0 Server mit 3 AI-Tools: + - `query` — SQL-Ausführung mit parametrisierten Abfragen + Multi-Tenant Session-Variablen + - `vector_search` — Semantische HNSW Vektor-suche mit Tenant-Isolation + - `schema_inspect` — Tabellen-/Spalten-/Index-/RLS-Policy-Exploration + - Standalone Binary: `build/baramcp` +- **Graph Engine Tiefe Integration** — `CREATE GRAPH` / `DROP GRAPH` DDL mit nativer Adjacency-List-Speicherung + - `GRAPH_TABLE()` SQL-Funktion mit 7 Algorithmen: BFS, DFS, PageRank, ShortestPath, Dijkstra, Louvain, Community + - INSERT in `_nodes`/`_edges` Tabellen synchronisiert automatisch mit nativen Graph-Objekten + - Optional `MATCH`, `ALGORITHM`, `START`, `END`, `MAXDEPTH` in GRAPH_TABLE Syntax +- **Chunking + Embedding Pipeline** — Serverseitige AI-Datenverarbeitung: + - `chunk()` SQL-Funktion — Text-Splitting mit konfigurierbarer Größe/Überlappung + - `embed_text()` SQL-Funktion — ruft externe Embedding-API auf (OpenAI/Ollama kompatibel) + - Auto-Embedding bei INSERT — wenn VECTOR-Spalte null ist, generiert aus TEXT-Spalte + - Konfigurierbar via Env-Vars: `BARADB_EMBED_ENDPOINT`, `BARADB_EMBED_MODEL`, `BARADB_EMBED_API_KEY` +- **LangChain ChatMessageHistory** — Python `BaraDBChatHistory` Klasse: + - Speichert Konversations-Threads in relationaler Tabelle mit RLS + - Multi-Tenant Isolation via `tenant_id` + `user_id` +- **RAG Pipeline Beispiel** — End-to-End Python Script (`examples/rag_pipeline.py`): + - PDF/text Ingestion → chunking → embedding → BaraDB Speicherung → hybrid search → LLM Generierung + - Unterstützt OpenAI und Ollama APIs +- **AI Agents & NL→SQL** — Serverseitige LLM-Integration: + - `nl_to_sql()` SQL-Funktion — natürliche Sprache → SQL Generierung + - `schema_prompt()` — generiert DDL + Beispieldaten für LLM-Kontext + - Abfrage-Validierungsschicht — Sandbox-Ausführung mit LIMIT 0 + EXPLAIN + - Selbst-Korrektur-Schleife — Fehlerfeedback an LLM zur Korrektur + - Konfigurierbar via Env-Vars: `BARADB_LLM_ENDPOINT`, `BARADB_LLM_MODEL`, `BARADB_LLM_API_KEY` +- **Graph Similarity & Embeddings**: + - `similarity_nodes()` — Jaccard/Adamic-Adar Ähnlichkeit zwischen Knotenpaaren + - `node2vec_embed()` — Random-walk basierte Graph Embeddings +- **Cypher Compatibility Layer**: + - `cypher()` SQL-Funktion — übersetzt `MATCH (a)-[r]->(b) RETURN ...` zu GRAPH_TABLE + - Automatische Cypher → BaraQL Konvertierung +- **German Documentation** — Vollständige Dokumentation auf Deutsch (`docs/de/`) + +### Geändert + +- Graph Executor upgraded von Stub zu echtem BFS/DFS/PageRank/Dijkstra/Louvain +- ExecutionContext erweitert mit `graphs`, `embedder`, `llmClient` Feldern +- Graph Engine erweitert mit `addNodeWithId`, `addEdgeWithId`, Jaccard, Adamic-Adar, node2vec + +## [1.1.0] — 2026-05-13 + +### Hinzugefügt + +- **Client SDKs v1.1.0** — Vollständige Clients für alle Sprachen: + - JavaScript: TypeScript Definitionen, package.json, Beispiele, Unit & Integration Tests + - Python: Umstrukturiert als proper Package (`baradb/` mit `__init__.py` und `core.py`), pyproject.toml, Beispiele, Tests + - Nim: Beispiele, Integration Tests, README + - Rust: Beispiele, Integration Tests, verbessertes Cargo.toml +- **SCRAM-SHA-256 Authentifizierung** — RFC 7677 konforme Authentifizierung mit PBKDF2 + HMAC + SHA-256 + Nonce/Salt Generierung +- **HTTP SCRAM Endpoints** — `/auth/scram/start` + `/auth/scram/finish` im HTTP Server +- **Docker Compose Test Configuration** — `docker-compose.test.yml` für Test-Umgebungen +- **CI/CD Clients Pipeline** — `.github/workflows/clients-ci.yml` für automatisierte Client-Tests + +### Behoben + +- **Query Executor** — Unärer Minus (`irNeg`) funktioniert jetzt korrekt in SELECT und WHERE Klauseln +- **Distributed Transactions** — Rollback nach Commit-Versuch verletzt nicht mehr Atomicity +- **Sharding** — Datenmigrations-Protokoll mit TCP + `scanAll` auf LSM +- **Raft** — Majority-Berechnung für gerade Knotenanzahl korrigiert +- **MVCC** — Abgebrochene Transaktionen werden nicht mehr sichtbar +- **LSM-Tree** — Datenverlust bei immutable memtable overwrite behoben; SSTable lookup sorting behoben +- **Auth** — JWT-Signatur auf HMAC-SHA256 geändert (nicht mehr trivial fälschbar); Token-Ablauf (`exp`/`nbf`/`iat`) wird jetzt validiert; Signatur-Vergleich ist jetzt constant-time +- **Recovery** — `summary()` mutiert die Datenbank nicht mehr +- **Wire Protocol** — 64MB Limit + Bounds Checking + Max Depth um OOM/DoS zu verhindern +- **SQL Injection** — `exprToSql` escaped jetzt Single Quotes +- **ReDoS** — `irLike`/`irILike` escaped jetzt Regex Metacharacters +- **Graph** — `addEdge` prüft jetzt Knotenexistenz +- **Vector** — Dimension mismatch Validierung + HNSW Locking +- **FTS** — UTF-8 Tokenisierung verwendet jetzt runes statt bytes +- **Build** — `nim.cfg` fügt `-d:ssl` hinzu damit `nimble build` ohne Flags funktioniert; `--threads:on` zu allen CI Commands hinzugefügt + +### Geändert + +- **Version auf 1.1.0 erhöht** über alle Komponenten +- **README** — Version Badge aktualisiert; alle Feature-Tabellen referenzieren jetzt v1.1.0 +- **TLA+ Formal Verification** — `crossmodal.tla`, `backup.tla`, `recovery.tla` hinzugefügt; Symmetrie-Reduktion in allen 9 Specs +- **Clean build** — 0 Compiler Warnings auf Nim 2.2.10 + +## [0.1.0] — 2025-01-15 + +### Hinzugefügt + +- **Core Storage Engines** + - LSM-Tree mit MemTable, WAL, SSTables und size-tiered Compaction + - B-Tree geordneter Index mit Range Scans und MVCC Copy-on-Write + - Bloom Filter für effizientes SSTable Skip + - Memory-mapped I/O für SSTable Reads + - LRU Page Cache mit Hit-Rate Tracking + +- **Query Engine (BaraQL)** + - SQL-kompatibler Lexer mit 80+ Tokentypen + - Rekursiver Descent Parser produziert AST mit 25+ Knotenarten + - Intermediate Representation (IR) für Ausführungspläne + - Code Generator übersetzt IR zu Speicheroperationen + - Adaptiver Query Optimizer mit Cross-Modal Planning + - Query Executor mit Parallelisierung + +- **BaraQL Language Features** + - SELECT, INSERT, UPDATE, DELETE + - WHERE, ORDER BY, LIMIT, OFFSET + - GROUP BY, HAVING, Aggregatfunktionen (count, sum, avg, min, max) + - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN + - CTEs (Common Table Expressions) mit WITH + - Subqueries (EXISTS, IN, correlated) + - CASE Expressions + - UNION, INTERSECT, EXCEPT + - Schema Definition: CREATE TYPE, DROP TYPE + +- **Vector Engine** + - HNSW Index für Approximate Nearest Neighbor Search + - IVF-PQ Index für Large-Scale Vector Search + - SIMD-optimierte Distanzfunktionen (cosine, L2, dot product, Manhattan) + - Quantization: scalar 8-bit/4-bit, product quantization, binary + - Metadata Filtering während Vector Search + +- **Graph Engine** + - Adjacency List Speicherung für gerichtete, kanten-gewichtete Graphen + - BFS und DFS Traversierung + - Dijkstra kürzester Pfad + - PageRank Knotenwichtigkeit + - Louvain Community Detection + - Subgraph Pattern Matching + - Cypher-ähnlicher Graph Query Parser + +- **Full-Text Search** + - Inverted Index mit Term-Document Mapping + - BM25 Ranking-Algorithmus + - TF-IDF Scoring + - Fuzzy Search mit Levenshtein Distanz + - Wildcard/regex Search + - Multi-Language Tokenizer (English, Bulgarian, German, French, Russian) + +- **Columnar Storage** + - Perspalten-Speicherung für analytische Abfragen + - RLE (Run-Length Encoding) Kompression + - Dictionary Encoding für Low-Cardinality Spalten + - SIMD-beschleunigte Aggregatfunktionen + +- **Transactions** + - MVCC (Multi-Version Concurrency Control) mit Snapshot Isolation + - Deadlock-Erkennung via Wait-for Graph + - Write-Ahead Log für Dauerhaftigkeit + - Savepoints und partielles Rollback + +- **Protocol Layer** + - Binary Wire Protocol mit 16 Nachrichtentypen + - HTTP/REST JSON API + - WebSocket Streaming + - Connection Pooling + - JWT-basierte Authentifizierung + - Token-bucket Rate Limiting + - TLS/SSL mit auto-generierten Zertifikaten + +- **Schema System** + - Starkes Typsystem mit 17 nativen Typen + - Typvererbung mit Multi-Base Support + - Property Links zwischen Typen + - Schema Diffing und Migrationen + - Computed Properties + +- **Distributed Systems** + - Raft Consensus (Leader Election, Log Replikation) + - Hash, Range und Consistent-Hash Sharding + - Sync/async/semi-sync Replikation + - Gossip Protocol für Membership Management + - Two-Phase Commit für Distributed Transactions + +- **Cross-Modal Queries** + - Vereinheitlichte Abfragesprache über alle Speicher-Engines + - Cross-Engine Predicate Pushdown + - Optimierte Ausführungspläne für Multi-Modal Abfragen + +- **Backup & Recovery** + - Online Snapshots ohne Ausfallzeit + - Point-in-Time Recovery via WAL Replay + - Inkrementelle Backups + +- **Client SDKs** + - JavaScript/TypeScript Client mit Binary Protocol + - Python Client mit Sync und Async APIs + - Nim Embedded Mode und Client Library + - Rust Client (async) + +- **Operations** + - Interaktive CLI Shell (BaraQL REPL) + - Strukturiertes Logging (JSON und Text Formate) + - Prometheus-kompatible Metrics Endpoint + - Health und Readiness Probes + - CPU/memory Profiling Endpoints + +- **Docker Support** + - Multi-stage Dockerfile (Alpine Linux) + - Docker Compose Konfiguration + - Health Checks + +### Performance + +- LSM-Tree: 580K writes/s, 720K reads/s +- B-Tree: 1.2M inserts/s, 1.5M lookups/s +- Vector SIMD: 850K cosine distances/s (dim=768) +- FTS: 320K docs/s indexing, 28K queries/s BM25 +- Graph: 2.5M nodes/s insertion, 12K BFS traversals/s +- Binary Protocol: 380K queries/s (100 concurrent connections) + +### Tests + +- 262 Tests über 56 Test-Suiten +- 100% Pass Rate + +## [Unreleased] + +### Hinzugefügt + +- **Vector SQL Integration** — Vollständige SQL-Level Vector Search Unterstützung: + - `VECTOR(n)` Spaltentyp in `CREATE TABLE` mit Dimensionsvalidierung + - `CREATE INDEX ... USING hnsw` / `USING ivfpq` für Approximate Nearest Neighbor Indizes + - SQL Distanzfunktionen: `cosine_distance()`, `euclidean_distance()`, `inner_product()`, `l1_distance()`, `l2_distance()` + - `<->` Nearest-Neighbor Operator (Euclidean Distanz) + - `ORDER BY` Support für Vektor-Distanz-Ausdrücke, inklusive Spalten nicht in `SELECT` + - Automatische HNSW Index-Wartung bei `INSERT` und `UPDATE` +- **Advanced SQL Engine** — Window Functions, MERGE/UPSERT, LATERAL JOIN, PIVOT/UNPIVOT, SQL/PGQ Property Graph, Advanced Aggregates +- **JavaScript Client — TCP Request Queue** — Interne `_requestQueue` + `_requestLock` für sichere konkurrierende Abfragen + +### Behoben + +- **Query Executor — Row Value Escaping** — `execInsert` escaped jetzt korrekt Kommas und Equals-Zeichen +- **Query Planner — ORDER BY Projection** — `irpkSort` ist jetzt vor `irpkProject` im IR Plan platziert +- **Wire Protocol — Big-Endian Float Serialization** — `FLOAT32`/`FLOAT64` werden jetzt in Big-Endian Byte-Reihenfolge serialisiert +- **Gossip Protocol — Async UDP Socket** — Synchrone `newSocket` + blocking `recvFrom` ersetzt durch `newAsyncSocket` + `await recvFrom` + +### Geplant + +- Query Plan Caching +- Materialized Views +- Geospatial Index +- Time-series Optimierungen +- CDC (Change Data Capture) Streaming +- Federated Queries über BaraDB Instances diff --git a/docs/de/clients.md b/docs/de/clients.md new file mode 100644 index 0000000..3c6fe34 --- /dev/null +++ b/docs/de/clients.md @@ -0,0 +1,285 @@ +# Client SDKs + +BaraDB bietet offizielle Client-Bibliotheken für JavaScript/TypeScript, Python, Nim und Rust. + +## JavaScript / TypeScript + +### Installation + +```bash +npm install baradb +# oder +yarn add baradb +``` + +### Grundlegende Verwendung + +```typescript +import { Client } from 'baradb'; + +const client = new Client('localhost', 9472); +await client.connect(); + +// Einfache Abfrage +const result = await client.query('SELECT name, age FROM users WHERE age > 18'); +console.log(result.rows); + +// Parametrisierte Abfrage +const result2 = await client.query( + 'SELECT * FROM users WHERE name = ?', + ['Alice'] +); + +// Batch-Einfügung +await client.batch([ + "INSERT users { name := 'Alice', age := 30 }", + "INSERT users { name := 'Bob', age := 25 }", +]); + +// Transaktionen +await client.begin(); +await client.query("INSERT orders { total := 100 }"); +await client.query("UPDATE users SET balance = balance - 100 WHERE name = 'Alice'"); +await client.commit(); + +await client.close(); +``` + +### Konkurrierende Abfragen + +Der JavaScript-Client serialisiert konkurrierende Anfragen über eine einzelne TCP-Verbindung automatisch via interner Request-Queue. Sie können sicher mehrere parallele Operationen starten — ihre Binärframes werden sich nicht auf dem Wire überlappen: + +```typescript +const [users, orders, stats] = await Promise.all([ + client.query('SELECT * FROM users'), + client.query('SELECT * FROM orders'), + client.query('SELECT count(*) FROM visits') +]); +``` + +### WebSocket-Streaming + +```typescript +import { WebSocketClient } from 'baradb/ws'; + +const ws = new WebSocketClient('ws://localhost:9471'); +ws.onMessage = (data) => console.log(data); +await ws.connect(); +await ws.send('SUBSCRIBE updates'); +``` + +## Python + +### Installation + +```bash +pip install baradb +``` + +### Grundlegende Verwendung + +```python +from baradb import Client + +client = Client("localhost", 9472) +client.connect() + +# Einfache Abfrage +result = client.query("SELECT name, age FROM users WHERE age > 18") +for row in result: + print(row["name"], row["age"]) + +# Parametrisierte Abfrage +result = client.query( + "SELECT * FROM users WHERE name = ?", + ["Alice"] +) + +# Batch-Operationen +client.batch([ + "INSERT users { name := 'Alice', age := 30 }", + "INSERT users { name := 'Bob', age := 25 }", +]) + +# Context Manager (auto-close) +with Client("localhost", 9472) as c: + result = c.query("SELECT count(*) FROM users") + print(result[0]["count"]) +``` + +### Async Client + +```python +import asyncio +from baradb import AsyncClient + +async def main(): + client = AsyncClient("localhost", 9472) + await client.connect() + result = await client.query("SELECT * FROM users") + print(result.rows) + await client.close() + +asyncio.run(main()) +``` + +## Nim (Embedded Mode) + +### Abhängigkeit hinzufügen + +```nim +# In Ihrer .nimble Datei +requires "barabadb >= 0.1.0" +``` + +### Embedded-Verwendung + +```nim +import barabadb/storage/lsm +import barabadb/storage/btree +import barabadb/vector/engine +import barabadb/graph/engine + +# Key-Value Store +var db = newLSMTree("./data") +db.put("user:1", cast[seq[byte]]("Alice")) +let (found, value) = db.get("user:1") +db.close() + +# B-Tree Index +var btree = newBTreeIndex[string, int]() +btree.insert("Alice", 30) +let ages = btree.get("Alice") + +# Vector Search +var idx = newHNSWIndex(dimensions = 128) +idx.insert(1, @[0.1'f32, 0.2, 0.3], {"category": "A"}.toTable) +let results = idx.search(@[0.1'f32, 0.2, 0.3], k = 10) + +# Graph +var g = newGraph() +let alice = g.addNode("Person", {"name": "Alice"}.toTable) +let bob = g.addNode("Person", {"name": "Bob"}.toTable) +discard g.addEdge(alice, bob, "knows") +let path = g.shortestPath(alice, bob) +``` + +### Client-Bibliothek + +```nim +import barabadb/client/client + +var c = newBaraClient("localhost", 9472) +c.connect() +let result = c.query("SELECT name FROM users") +for row in result.rows: + echo row["name"] +c.close() +``` + +## Rust + +### Abhängigkeit hinzufügen + +```toml +[dependencies] +baradb = "0.1" +tokio = { version = "1", features = ["full"] } +``` + +### Grundlegende Verwendung + +```rust +use baradb::Client; + +#[tokio::main] +async fn main() -> Result<(), Box> { + let mut client = Client::connect("localhost:9472").await?; + + let result = client + .query("SELECT name, age FROM users WHERE age > 18") + .await?; + + for row in result.rows { + println!("{} is {} years old", row["name"], row["age"]); + } + + client.close().await?; + Ok(()) +} +``` + +## HTTP/REST (Sprachunabhängig) + +Alle Sprachen können die HTTP/REST API direkt verwenden: + +```bash +# Abfrage +curl -X POST http://localhost:9470/api/query \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"query": "SELECT * FROM users WHERE age > 18"}' + +# Einfügen +curl -X POST http://localhost:9470/api/query \ + -H "Content-Type: application/json" \ + -d '{"query": "INSERT users { name := \"Alice\", age := 30 }"}' + +# Schema +curl http://localhost:9470/api/schema + +# Health +curl http://localhost:9470/health + +# Metrics +curl http://localhost:9470/metrics +``` + +## Connection Pooling + +Alle offiziellen Clients unterstützen Connection Pooling: + +### JavaScript + +```typescript +import { Pool } from 'baradb'; + +const pool = new Pool({ + host: 'localhost', + port: 9472, + min: 5, + max: 50, + idleTimeout: 30000, +}); + +const client = await pool.acquire(); +try { + const result = await client.query('SELECT 1'); +} finally { + pool.release(client); +} +``` + +### Python + +```python +from baradb import Pool + +pool = Pool("localhost", 9472, min_size=5, max_size=50) +with pool.connection() as conn: + result = conn.query("SELECT 1") +``` + +## Datentyp-Mapping + +| BaraDB Type | JavaScript | Python | Nim | Rust | +|-------------|------------|--------|-----|------| +| `null` | `null` | `None` | `nil` | `Option::None` | +| `bool` | `boolean` | `bool` | `bool` | `bool` | +| `int8/16/32/64` | `number` | `int` | `int` | `i8/i16/i32/i64` | +| `float32/64` | `number` | `float` | `float32/float64` | `f32/f64` | +| `str` | `string` | `str` | `string` | `String` | +| `bytes` | `Uint8Array` | `bytes` | `seq[byte]` | `Vec` | +| `array` | `Array` | `list` | `seq` | `Vec` | +| `object` | `Object` | `dict` | `Table` | `HashMap` | +| `vector` | `Float32Array` | `list[float]` | `seq[float32]` | `Vec` | diff --git a/docs/de/columnar.md b/docs/de/columnar.md new file mode 100644 index 0000000..de6db0e --- /dev/null +++ b/docs/de/columnar.md @@ -0,0 +1,58 @@ +# Kolumnare Speicherung + +Spaltenorientierte Speicherung für analytische Abfragen und Aggregation. + +## Verwendung + +```nim +import barabadb/core/columnar + +var batch = newColumnBatch() +var ageCol = batch.addInt64Col("age") +var nameCol = batch.addStringCol("name") + +ageCol.appendInt64(25) +nameCol.appendString("Alice") +``` + +## Aggregation + +```nim +echo ageCol.sumInt64() +echo ageCol.avgInt64() +echo ageCol.minInt64() +echo ageCol.maxInt64() +echo ageCol.count() +``` + +## Kodierung + +### RLE (Run-Length Encoding) + +```nim +let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) +``` + +### Dictionary-Kodierung + +```nim +let dict = dictEncode(@["apple", "banana", "apple"]) +``` + +## Spaltentypen + +| Typ | Beschreibung | +|------|-------------| +| `int32` | 32-Bit Integer | +| `int64` | 64-Bit Integer | +| `float32` | 32-Bit Float | +| `float64` | 64-Bit Float | +| `string` | Variable-length String | +| `bool` | Boolean | + +## Anwendungsfälle + +- OLAP-Workloads +- Großflächige Aggregation +- Data Warehousing +- Zeitreihenanalyse diff --git a/docs/de/configuration.md b/docs/de/configuration.md new file mode 100644 index 0000000..71ee40c --- /dev/null +++ b/docs/de/configuration.md @@ -0,0 +1,217 @@ +# Konfigurationsreferenz + +BaraDB kann über **Environment-Variablen**, eine **Konfigurationsdatei** oder **Kommandozeilen-Flags** konfiguriert werden. + +## Prioritätsreihenfolge + +1. Kommandozeilen-Flags (höchste Priorität) +2. Environment-Variablen +3. Konfigurationsdatei (`baradb.conf` oder `baradb.json`) +4. Integrierte Standardwerte (niedrigste Priorität) + +## Environment-Variablen + +### Netzwerk + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_ADDRESS` | `127.0.0.1` | Bind-Adresse | +| `BARADB_PORT` | `9472` | TCP Binary Protocol Port | +| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API Port | +| `BARADB_WS_PORT` | `9471` | WebSocket Port | + +### Speicher + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_DATA_DIR` | `./data` | Datenverzeichnis-Pfad | +| `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable-Größe in MB | +| `BARADB_CACHE_SIZE_MB` | `256` | Page-Cache-Größe in MB | +| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | WAL fsync Intervall (0 = bei jedem Write) | +| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | Background Compaction Intervall | +| `BARADB_BLOOM_BITS_PER_KEY` | `10` | Bloom-Filter Bits pro Schlüssel | + +### TLS/SSL + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_TLS_ENABLED` | `false` | TLS aktivieren | +| `BARADB_CERT_FILE` | — | Pfad zum TLS-Zertifikat | +| `BARADB_KEY_FILE` | — | Pfad zum TLS Private Key | + +### Sicherheit + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_AUTH_ENABLED` | `false` | Authentifizierung aktivieren | +| `BARADB_JWT_SECRET` | — | JWT Signatur-Geheimnis | +| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Globale Requests pro Sekunde | +| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | Per-Client Requests pro Sekunde | + +### Logging + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_LOG_LEVEL` | `info` | Log-Level: debug, info, warn, error | +| `BARADB_LOG_FILE` | — | Log-Datei-Pfad (stdout wenn leer) | +| `BARADB_LOG_FORMAT` | `json` | Log-Format: json, text | + +### Vector Engine + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_VECTOR_M` | `16` | HNSW `M` Parameter | +| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` | +| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` | + +### Graph Engine + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | PageRank Iterationsanzahl | +| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank Dämpfungsfaktor | +| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain Resolution-Parameter | + +### Distributed + +| Variable | Standard | Beschreibung | +|----------|---------|-------------| +| `BARADB_RAFT_NODE_ID` | — | Eindeutige Knoten-ID im Cluster | +| `BARADB_RAFT_PEERS` | — | Komma-getrennte Liste von Peer-Adressen | +| `BARADB_RAFT_PORT` | `9001` | Raft interne Kommunikation Port | +| `BARADB_SHARD_COUNT` | `1` | Anzahl der Shards | +| `BARADB_REPLICATION_FACTOR` | `1` | Replikationsfaktor | + +## Konfigurationsdatei + +### baradb.conf (INI-ähnlich) + +```ini +[server] +address = "0.0.0.0" +port = 9472 +http_port = 9470 +ws_port = 9471 + +[storage] +data_dir = "/var/lib/baradb" +memtable_size_mb = 256 +cache_size_mb = 512 +wal_sync_interval_ms = 10 +compaction_interval_ms = 30000 + +[tls] +enabled = true +cert_file = "/etc/baradb/server.crt" +key_file = "/etc/baradb/server.key" + +[auth] +enabled = true +jwt_secret = "change-me-in-production" +rate_limit_global = 10000 +rate_limit_per_client = 1000 + +[logging] +level = "info" +format = "json" +file = "/var/log/baradb/baradb.log" + +[vector] +m = 16 +ef_construction = 200 +ef_search = 64 + +[cluster] +raft_node_id = "node1" +raft_peers = "node2:9001,node3:9001" +``` + +### baradb.json + +```json +{ + "server": { + "address": "0.0.0.0", + "port": 9472, + "http_port": 9470, + "ws_port": 9471 + }, + "storage": { + "data_dir": "/var/lib/baradb", + "memtable_size_mb": 256, + "cache_size_mb": 512 + }, + "tls": { + "enabled": true, + "cert_file": "/etc/baradb/server.crt", + "key_file": "/etc/baradb/server.key" + } +} +``` + +## Kommandozeilen-Flags + +```bash +./build/baradadb --help +``` + +``` +BaraDB v1.1.0 — Multimodal Database Engine + +Usage: + baradadb [options] + +Options: + -c, --config Config file path + -p, --port TCP binary port (default: 9472) + --http-port HTTP port (default: 9470) + --ws-port WebSocket port (default: 9471) + -d, --data-dir Data directory (default: ./data) + --tls-cert TLS certificate file + --tls-key TLS private key file + --log-level Log level: debug, info, warn, error + --log-file Log file path + --shell Start interactive shell + --version Show version + --recover Run WAL recovery + --checkpoint Checkpoint for recovery + -h, --help Show this help +``` + +## Beispielkonfigurationen + +### Entwicklung + +```bash +./build/baradadb \ + --log-level debug \ + --data-dir ./dev_data +``` + +### Produktion Single Node + +```bash +BARADB_TLS_ENABLED=true \ +BARADB_CERT_FILE=/etc/baradb/server.crt \ +BARADB_KEY_FILE=/etc/baradb/server.key \ +BARADB_AUTH_ENABLED=true \ +BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ +BARADB_LOG_LEVEL=warn \ +BARADB_LOG_FILE=/var/log/baradb/baradb.log \ +BARADB_MEMTABLE_SIZE_MB=256 \ +BARADB_CACHE_SIZE_MB=1024 \ +./build/baradadb +``` + +### Produktion Cluster (3 Knoten) + +```bash +# Knoten 1 +BARADB_ADDRESS=0.0.0.0 \ +BARADB_PORT=9472 \ +BARADB_RAFT_NODE_ID=node1 \ +BARADB_RAFT_PEERS=node2:9001,node3:9001 \ +BARADB_SHARD_COUNT=4 \ +BARADB_REPLICATION_FACTOR=2 \ +./build/baradadb +``` diff --git a/docs/de/crossmodal.md b/docs/de/crossmodal.md new file mode 100644 index 0000000..aa25287 --- /dev/null +++ b/docs/de/crossmodal.md @@ -0,0 +1,218 @@ +# Cross-Modal Abfragen + +BaraDB's einzigartige Fähigkeit ist die Ausführung von Abfragen, die mehrere +Speicher-Engines in einer einzigen vereinheitlichten BaraQL-Anweisung umfassen. + +## Überblick + +Traditionelle Datenbanken erfordern separate Abfragen und applikationsseitige Joins +bei der Arbeit mit verschiedenen Datenmodellen. BaraDB's Cross-Modal Query Planner +optimiert die Ausführung über: + +- **Document/KV** (LSM-Tree) — strukturierte Datensätze +- **Graph** (Adjacency List) — Beziehungen +- **Vector** (HNSW/IVF-PQ) — Ähnlichkeitssuche +- **Full-Text** (Inverted Index) — Textsuche +- **Columnar** — analytische Aggregatfunktionen + +## Abfragemuster + +### Vector + Full-Text (Semantisch + Schlüsselwortsuche) + +Finde Dokumente, die semantisch ähnlich zu einem Query-Vektor sind UND +bestimmte Schlüsselwörter enthalten: + +```sql +SELECT title, score +FROM articles +WHERE MATCH(body) AGAINST('machine learning') +ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, ...]) +LIMIT 10; +``` + +Ausführungsplan: +1. FTS-Engine filtert Artikel mit "machine learning" +2. Vector-Engine rankt gefilterte Ergebnisse nach Embedding-Ähnlichkeit +3. Top-K Ergebnisse zurückgegeben + +### Graph + Vector (Soziale Empfehlungen) + +Finde Freunde eines Benutzers mit ähnlichen Geschmacksvektoren: + +```sql +MATCH (u:User)-[:KNOWS]->(friend:User) +WHERE u.name = 'Alice' +ORDER BY cosine_distance(friend.taste_vector, u.taste_vector) +RETURN friend.name, friend.age; +``` + +Ausführungsplan: +1. Graph-Engine traversiert "KNOWS"-Kanten von Alice +2. Vector-Engine berechnet Ähnlichkeit für jeden Freund +3. Ergebnisse sortiert und projiziert + +### Document + Graph (Entity-Anreicherung) + +Erhalte Bestelldetails mit Kunden-Beziehungsgraph: + +```sql +SELECT o.id, o.total, c.name, + (SELECT count(*) FROM orders WHERE customer_id = c.id) as order_count +FROM orders o +JOIN customers c ON o.customer_id = c.id +WHERE c.id IN ( + SELECT node_id FROM graph + WHERE MATCH pattern (c:Customer)-[:REFERRED]->(:Customer) +); +``` + +### Full-Text + Aggregate (Content-Analyse) + +Analysiere welche Abteilungen am meisten über ein Thema schreiben: + +```sql +SELECT department, count(*) as article_count, + avg(length(content)) as avg_length +FROM docs +WHERE MATCH(content) AGAINST('Nim programming') +GROUP BY department +ORDER BY article_count DESC; +``` + +### Vector + Aggregate (Cluster-Analyse) + +Gruppiere ähnliche Vektoren und analysiere jedes Cluster: + +```sql +SELECT cluster_id, count(*) as size, + centroid(embedding) as center, + avg(created_at) as avg_date +FROM products +GROUP BY vector_cluster(embedding, k=10) +ORDER BY size DESC; +``` + +### Alle Modalitäten kombiniert + +Eine komplexe Abfrage unter Verwendung aller Engines: + +```sql +WITH relevant_docs AS ( + SELECT id, title, embedding + FROM articles + WHERE MATCH(body) AGAINST('database optimization') + AND created_at > '2024-01-01' +), +author_graph AS ( + MATCH (a:Author)-[:COAUTHORED]->(b:Author) + WHERE a.name = 'Dr. Smith' + RETURN b.id as coauthor_id +) +SELECT rd.title, rd.score, + a.name as author, + cosine_distance(rd.embedding, query_vec) as similarity +FROM relevant_docs rd +JOIN authors a ON rd.author_id = a.id +WHERE a.id IN (SELECT coauthor_id FROM author_graph) +ORDER BY similarity ASC, rd.score DESC +LIMIT 20; +``` + +## Optimierung + +### Cross-Modal Query Planner + +BaraDB's adaptiver Query-Optimizer (`query/adaptive.nim`) wählt die Ausführungsreihenfolge basierend auf Selektivität: + +``` +1. Selektivstes Filter zuerst (normalerweise FTS oder Vector) +2. Prädikate zu jeder Engine pushen +3. Bloom-Filter für KV-Lookups verwenden +4. Unabhängige Zweige parallelisieren +``` + +### Index-Auswahl + +Der Optimizer wählt automatisch den besten Index: + +| Abfragemuster | Primäre Engine | Sekundäre Engine | +|---------------|----------------|-----------------| +| `MATCH ... ORDER BY cosine_distance` | Vector | FTS | +| `MATCH ... WHERE graph condition` | Graph | FTS | +| `WHERE id = ? AND vector_search` | KV | Vector | +| `GROUP BY + MATCH` | FTS | Columnar | + +### Hints + +Bestimmte Ausführungsreihenfolge erzwingen: + +```sql +SELECT /*+ USE_INDEX(vector) */ * +FROM products +WHERE category = 'electronics' +ORDER BY cosine_distance(embedding, [...]) +LIMIT 10; +``` + +## Performance + +Cross-Modal Abfragen sind optimiert um Datenbewegung zu minimieren: + +| Abfragetyp | Latenz (10K Zeilen) | Latenz (100K Zeilen) | +|------------|---------------------|----------------------| +| FTS + Vector | 15 ms | 85 ms | +| Graph + Vector | 25 ms | 120 ms | +| FTS + Aggregate | 12 ms | 55 ms | +| Alle Modalitäten | 45 ms | 220 ms | + +## Anwendungsfälle + +### E-Commerce Suche + +```sql +-- Finde Produkte passend zu einem Suchbegriff, ähnlich zu einem betrachteten Artikel, +-- gekauft von ähnlichen Benutzern +SELECT p.name, p.price +FROM products p +WHERE MATCH(p.description) AGAINST('wireless headphones') + AND cosine_distance(p.embedding, viewed_embedding) < 0.3 + AND p.id IN ( + SELECT product_id FROM orders o + JOIN graph ON o.customer_id = graph.node_id + WHERE graph.similarity > 0.8 + ) +ORDER BY p.rating DESC +LIMIT 20; +``` + +### Betrugserkennung + +```sql +-- Finde Transaktionen ähnlich zu bekannten Betrugsmustern, +-- wo der Benutzer mit markierten Konten verbunden ist +SELECT t.id, t.amount +FROM transactions t +WHERE cosine_distance(t.pattern_vector, fraud_vector) < 0.2 + AND t.user_id IN ( + MATCH (u:User)-[*1..3]->(f:FlaggedAccount) + RETURN u.id + ); +``` + +### Knowledge Graph + RAG + +```sql +-- Relevante Dokumente für eine Query abrufen, +-- dann den Knowledge Graph für verwandte Konzepte traversieren +WITH docs AS ( + SELECT id, content, embedding + FROM documents + ORDER BY cosine_distance(embedding, query_embedding) + LIMIT 5 +) +SELECT d.content, c.name as related_concept +FROM docs d +JOIN graph ON d.id = graph.doc_id +MATCH (d)-[:MENTIONS]->(c:Concept) +RETURN d.content, c.name; +``` diff --git a/docs/de/deployment.md b/docs/de/deployment.md new file mode 100644 index 0000000..f195efb --- /dev/null +++ b/docs/de/deployment.md @@ -0,0 +1,247 @@ +# Deployment-Leitfaden + +## Docker + +### Schnellstart + +```bash +docker build -t baradb:latest . +docker compose up -d +``` + +### Docker Compose Dateien + +| Datei | Zweck | +|-------|-------| +| `docker-compose.yml` | Entwicklung | +| `docker-compose.prod.yml` | Produktion | +| `docker-compose.override.yml` | Dev Override (automatisch) | + +### Produktion + +```bash +docker compose -f docker-compose.prod.yml up -d +``` + +### Docker Swarm + +```bash +docker stack deploy -c docker-compose.prod.yml baradb +``` + +## systemd Service + +Erstelle `/etc/systemd/system/baradb.service`: + +```ini +[Unit] +Description=BaraDB Multimodal Database +After=network.target + +[Service] +Type=simple +User=baradb +Group=baradb +WorkingDirectory=/var/lib/baradb +ExecStart=/usr/local/bin/baradadb +Restart=always +RestartSec=5 + +Environment=BARADB_PORT=9472 +Environment=BARADB_HTTP_PORT=9470 +Environment=BARADB_DATA_DIR=/var/lib/baradb/data +Environment=BARADB_LOG_LEVEL=info + +# Security hardening +NoNewPrivileges=true +ProtectSystem=strict +ProtectHome=true +ReadWritePaths=/var/lib/baradb/data +ProtectKernelTunables=true +ProtectKernelModules=true +ProtectControlGroups=true + +[Install] +WantedBy=multi-user.target +``` + +Aktivieren und starten: + +```bash +sudo useradd -r -s /bin/false baradb +sudo mkdir -p /var/lib/baradb/data +sudo chown -R baradb:baradb /var/lib/baradb +sudo cp build/baradadb /usr/local/bin/ +sudo systemctl daemon-reload +sudo systemctl enable --now baradb +``` + +## Kubernetes + +### StatefulSet + +```yaml +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: baradb +spec: + serviceName: baradb + replicas: 3 + selector: + matchLabels: + app: baradb + template: + metadata: + labels: + app: baradb + spec: + containers: + - name: baradb + image: baradb:latest + ports: + - containerPort: 9472 + name: binary + - containerPort: 9470 + name: http + - containerPort: 9471 + name: websocket + env: + - name: BARADB_DATA_DIR + value: /data + - name: BARADB_RAFT_NODE_ID + valueFrom: + fieldRef: + fieldPath: metadata.name + volumeMounts: + - name: data + mountPath: /data + volumeClaimTemplates: + - metadata: + name: data + spec: + accessModes: ["ReadWriteOnce"] + resources: + requests: + storage: 100Gi +--- +apiVersion: v1 +kind: Service +metadata: + name: baradb +spec: + selector: + app: baradb + ports: + - port: 9472 + name: binary + - port: 9470 + name: http + - port: 9471 + name: websocket + clusterIP: None +``` + +## Reverse Proxy (nginx) + +```nginx +upstream baradb_http { + server 127.0.0.1:9470; +} + +upstream baradb_ws { + server 127.0.0.1:9471; +} + +server { + listen 80; + server_name db.example.com; + return 301 https://$server_name$request_uri; +} + +server { + listen 443 ssl http2; + server_name db.example.com; + + ssl_certificate /etc/letsencrypt/live/db.example.com/fullchain.pem; + ssl_certificate_key /etc/letsencrypt/live/db.example.com/privkey.pem; + + location /api/ { + proxy_pass http://baradb_http/; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } + + location /ws/ { + proxy_pass http://baradb_ws/; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +``` + +## High Availability + +### 3-Node Raft Cluster + +```bash +# Knoten 1 +BARADB_RAFT_NODE_ID=node1 \ +BARADB_RAFT_PEERS=node2:9001,node3:9001 \ +./build/baradadb + +# Knoten 2 +BARADB_RAFT_NODE_ID=node2 \ +BARADB_RAFT_PEERS=node1:9001,node3:9001 \ +./build/baradadb + +# Knoten 3 +BARADB_RAFT_NODE_ID=node3 \ +BARADB_RAFT_PEERS=node1:9001,node2:9001 \ +./build/baradadb +``` + +## Cloud Deployment + +### AWS EC2 + +Empfohlene Instance: `m6i.2xlarge` (8 vCPU, 32 GB RAM) + +```bash +# User data script +#!/bin/bash +apt-get update +apt-get install -y nim +wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64 +chmod +x baradadb-linux-amd64 +mv baradadb-linux-amd64 /usr/local/bin/baradadb + +mkdir -p /data/baradb +cat > /etc/systemd/system/baradb.service << 'EOF' +[Unit] +Description=BaraDB +After=network.target +[Service] +ExecStart=/usr/local/bin/baradadb +Environment=BARADB_DATA_DIR=/data/baradb +Restart=always +[Install] +WantedBy=multi-user.target +EOF + +systemctl daemon-reload +systemctl enable --now baradb +``` + +### GCP Cloud Run (nur HTTP) + +```bash +gcloud run deploy baradb \ + --image gcr.io/PROJECT/baradb \ + --port 9470 \ + --memory 4Gi \ + --cpu 2 \ + --max-instances 10 +``` diff --git a/docs/de/distributed.md b/docs/de/distributed.md new file mode 100644 index 0000000..f5f45f5 --- /dev/null +++ b/docs/de/distributed.md @@ -0,0 +1,110 @@ +# Distributed Systems + +BaraDB unterstützt verteiltes Deployment mit Raft Consensus, Sharding und Replikation. + +## Raft Consensus + +Leader Election und Log-Replikation: + +```nim +import barabadb/core/raft + +var cluster = newRaftCluster() +cluster.addNode("node1") +cluster.addNode("node2") +cluster.addNode("node3") + +let n1 = cluster.nodes["n1"] +n1.becomeCandidate() +n1.becomeLeader() +let entry = n1.appendLog("SET key1 value1") +``` + +## Sharding + +Daten über Knoten verteilen: + +```nim +import barabadb/core/sharding + +var router = newShardRouter(ShardConfig( + numShards: 4, + replicas: 2, + strategy: ssHash +)) +router.rebalance(@["node1", "node2", "node3"]) +let shard = router.getShard("user_123") +``` + +### Sharding-Strategien + +| Strategie | Beschreibung | +|----------|-------------| +| `ssHash` | Hash-basiertes Sharding | +| `ssRange` | Range-basiertes Sharding | +| `ssConsistent` | Consistent Hashing | + +## Replikation + +```nim +import barabadb/core/replication + +var rm = newReplicationManager(rmSync) +rm.addReplica(newReplica("r1", "10.0.0.1", 9472)) +rm.connectReplica("r1") +let lsn = rm.writeLsn(@[1'u8, 2, 3]) +rm.ackLsn("r1", lsn) +``` + +### Replikationsmodi + +| Modus | Beschreibung | +|-------|--------------| +| `rmSync` | Synchronous Replikation | +| `rmAsync` | Asynchrone Replikation | +| `rmSemiSync` | Semi-synchrone Replikation | + +## Gossip Protocol + +Membership und Failure-Erkennung: + +```nim +import barabadb/core/gossip + +var g = newGossipManager() +g.addNode("node1") +g.addNode("node2") +g.tick() # Membership-Info austauschen +``` + +## Distributed Transactions + +Two-Phase Commit über Knoten: + +```nim +import barabadb/core/disttxn + +var dt = newDistributedTxn() +dt.prepare(@["node1", "node2"]) +dt.commit() +``` + +## Formale Verifikation + +Kern-Algorithmen für Distributed Systems sind formal in TLA+ spezifiziert und model-gecheckt: + +- **Raft Consensus** — `formal-verification/raft.tla` + - Verifiziert: ElectionSafety, StateMachineSafety +- **Two-Phase Commit** — `formal-verification/twopc.tla` + - Verifiziert: Atomicity, NoOrphanBlocks +- **Replication** — `formal-verification/replication.tla` + - Verifiziert: MonotonicLsn, AcksRemovePending + +TLC lokal ausführen: + +```bash +cd formal-verification +java -cp tla2tools.jar tlc2.TLC -config models/raft.cfg raft.tla +java -cp tla2tools.jar tlc2.TLC -config models/twopc.cfg twopc.tla +java -cp tla2tools.jar tlc2.TLC -config models/replication.cfg replication.tla +``` diff --git a/docs/de/docker.md b/docs/de/docker.md new file mode 100644 index 0000000..face19c --- /dev/null +++ b/docs/de/docker.md @@ -0,0 +1,191 @@ +# Docker Deployment-Leitfaden + +Dieser Leitfaden beschreibt, wie Sie BaraDB mit Docker und Docker Compose verwenden. + +## Schnellstart + +```bash +# Repository klonen +git clone https://codeberg.org/baraba/baradb +cd barabaDB + +# Image bauen +docker build -t baradb:latest . + +# Mit Docker Compose starten +docker compose up -d + +# Status prüfen +docker compose ps +docker compose logs -f +``` + +## Dateien + +| Datei | Beschreibung | +|-------|--------------| +| `Dockerfile` | Multi-stage Production Build | +| `docker-compose.yml` | Development Konfiguration | +| `docker-compose.prod.yml` | Production Konfiguration | +| `docker-compose.override.yml` | Development Override (wird automatisch geladen) | +| `docker-entrypoint.sh` | Entrypoint-Skript für Initialisierung | +| `.dockerignore` | Dateien, die nicht ins Image kopiert werden sollen | +| `scripts/docker-build.sh` | Helper-Skript für Build | +| `scripts/docker-run.sh` | Helper-Skript für manuelles Starten | + +## Image erstellen + +```bash +# Standard Build +docker build -t baradb:latest . + +# Mit Skript +./scripts/docker-build.sh + +# Mit bestimmter Version +IMAGE_NAME=baradb VERSION=0.1.0 ./scripts/docker-build.sh +``` + +## Starten + +### Development (docker compose) + +```bash +# Im Hintergrund starten +docker compose up -d + +# Stoppen +docker compose down + +# Stoppen und Volumes löschen (WARNUNG — löscht Daten!) +docker compose down -v + +# Logs ansehen +docker compose logs -f +``` + +### Production (docker compose) + +```bash +# Mit Production-Konfiguration starten +docker compose -f docker-compose.prod.yml up -d + +# Healthcheck prüfen +docker compose -f docker-compose.prod.yml ps +``` + +### Manuell (docker run) + +```bash +# Mit Skript +./scripts/docker-run.sh + +# Manuell +docker run -d \ + --name baradb \ + -p 9472:9472 \ + -p 9470:9470 \ + -p 9471:9471 \ + -v baradb_data:/data \ + -e BARADB_LOG_LEVEL=info \ + baradb:latest +``` + +## Ports + +| Port | Beschreibung | +|------|--------------| +| `9472` | Binary Wire Protocol | +| `9912` | HTTP/REST API (TCP port + 440) | +| `9913` | WebSocket (TCP port + 441) | + +## Environment Variables + +| Variable | Standardwert | Beschreibung | +|----------|--------------|--------------| +| `BARADB_ADDRESS` | `0.0.0.0` | Bind-Adresse | +| `BARADB_PORT` | `9472` | Binary Protocol Port | +| `BARADB_HTTP_PORT` | `9470` | HTTP Port | +| `BARADB_WS_PORT` | `9471` | WebSocket Port | +| `BARADB_DATA_DIR` | `/data` | Datenverzeichnis | +| `BARADB_LOG_LEVEL` | `info` | Log-Level | + +## Volumes + +| Pfad im Container | Beschreibung | +|-------------------|--------------| +| `/data` | Hauptdatenverzeichnis | +| `/data/server/wal` | Write-Ahead Log | +| `/data/server/sstables` | SSTable Dateien | + +## Production Checklist + +- [ ] TLS-Zertifikate in `./certs/` erstellen +- [ ] Starkes `BARADB_JWT_SECRET` setzen +- [ ] Firewall-Regeln konfigurieren +- [ ] Regelmäßige Backups konfigurieren +- [ ] Resource Limits prüfen +- [ ] Monitoring einrichten (Healthcheck, Logs) + +## TLS in Docker + +1. Zertifikate erstellen: +```bash +mkdir -p certs +openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ + -keyout certs/server.key -out certs/server.crt +``` + +2. In `docker-compose.prod.yml` aktivieren: +```yaml +environment: + - BARADB_TLS_ENABLED=true + - BARADB_CERT_FILE=/certs/server.crt + - BARADB_KEY_FILE=/certs/server.key +volumes: + - ./certs:/certs:ro +``` + +## Backup in Docker + +```bash +# Manueller Backup +docker exec baradb /app/backup backup --data-dir=/data + +# Backup-Liste +docker exec baradb /app/backup list + +# Wiederherstellung +docker exec baradb /app/backup restore --input=backup_xxx.tar.gz +``` + +## Troubleshooting + +### Container startet nicht + +```bash +# Logs prüfen +docker compose logs -f baradb + +# Status prüfen +docker compose ps +``` + +### Keine Verbindung zur Datenbank + +```bash +# Prüfen ob Ports exponiert sind +docker port baradb + +# Von innen prüfen +docker exec baradb wget -qO- http://localhost:9470/health +``` + +### Permission denied auf /data + +Das Entrypoint-Skript erstellt automatisch Verzeichnisse und setzt korrekte Permissions. Bei Problemen: + +```bash +docker exec baradb ls -la /data +docker exec baradb chown -R baradb:baradb /data +``` diff --git a/docs/de/fts.md b/docs/de/fts.md new file mode 100644 index 0000000..4d98aa5 --- /dev/null +++ b/docs/de/fts.md @@ -0,0 +1,87 @@ +# Volltextsuchmaschine + +Invertierter Index mit BM25 und TF-IDF-Ranking für Textsuche. + +## Verwendung + +```nim +import barabadb/fts/engine + +var idx = newInvertedIndex() +idx.addDocument(1, "Nim is a fast programming language") +idx.addDocument(2, "Python is popular for data science") + +# BM25-Suche +let results = idx.search("programming language") + +# TF-IDF-Suche +let tfidf = idx.searchTfidf("programming language") + +# Fuzzy-Suche (Tippfehlertoleranz) +let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) + +# Platzhalter-Suche +let wild = idx.regexSearch("prog*") +``` + +## Ranking-Methoden + +### BM25 + +Best-Matching-Ranking-Algorithmus: + +```nim +let bm25 = idx.searchBM25("query terms") +``` + +### TF-IDF + +Term Frequency-Inverse Document Frequency: + +```nim +let tfidf = idx.searchTfidf("query terms") +``` + +## Suchfunktionen + +| Funktion | Beschreibung | +|---------|-------------| +| Fuzzy-Suche | Levenshtein-Distanz-Toleranz | +| Platzhalter | Präfix-, Suffix- und Infix-Platzhalter | +| Regex | Reguläre Ausdrucksmuster | +| Phrasensuche | Exakte Phrasenübereinstimmung | +| Boolesch | AND, OR, NOT Operatoren | + +## SQL-Schnittstelle + +Volltextsuche ist auch direkt in BaraQL verfügbar: + +```sql +-- Tabelle mit Textspalte erstellen +CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, body TEXT); + +-- FTS-Index erstellen +CREATE INDEX idx_fts ON articles(body) USING FTS; + +-- Suche mit dem @@ Operator (BM25-Ranking) +SELECT * FROM articles WHERE body @@ 'machine learning'; + +-- Suche mit mehreren Begriffen +SELECT * FROM articles WHERE body @@ 'quick brown fox'; +``` + +## Mehrsprachige Unterstützung + +```nim +import barabadb/fts/multilang + +# Unterstützte Sprachen: EN, BG, DE, FR, RU +var tokenizer = newTokenizer("de") # Deutsch +let tokens = tokenizer.tokenize("Volltextsuche") +``` + +Funktionen pro Sprache: +- Tokenisierung +- Stoppwörter +- Stemming +- Spracherkennung diff --git a/docs/de/lsm.md b/docs/de/lsm.md new file mode 100644 index 0000000..4cb8a59 --- /dev/null +++ b/docs/de/lsm.md @@ -0,0 +1,64 @@ +# LSM-Tree Speicher-Engine + +Die primäre Speicher-Engine in BaraDB mit Log-Structured Merge-Tree Architektur. + +## Architektur + +``` +┌─────────────────────────────────────────────┐ +│ Writes │ +│ (append to WAL + MemTable) │ +└─────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────┐ +│ MemTable │ +│ (in-memory sorted buffer) │ +└─────────────────────────────────────────────┘ + │ + (when full, flush to SSTable) + │ + ▼ +┌─────────────────────────────────────────────┐ +│ SSTable │ +│ (sorted string table on disk) │ +└─────────────────────────────────────────────┘ +``` + +## Verwendung + +```nim +import barabadb/storage/lsm + +var db = newLSMTree("./data") + +# Schreiben +db.put("key1", cast[seq[byte]]("value1")) + +# Lesen +let (found, value) = db.get("key1") + +# Löschen +db.delete("key1") + +db.close() +``` + +## Funktionen + +- **Write-optimiert**: Append-only Log-Struktur +- **Dauerhaftigkeit**: Write-Ahead Log (WAL) sichert Crash-Wiederherstellung +- **Bloom-Filter**: Schnelle negative Lookups +- **Compaction**: Size-tiered Strategie mischt SSTables +- **Page-Cache**: LRU-Cache für häufig zugegriffene Seiten + +## Konfiguration + +```nim +var db = newLSMTree( + path = "./data", + memTableSize = 64 * 1024 * 1024, # 64MB + walEnabled = true, + bloomFpRate = 0.01 +) +``` diff --git a/docs/de/monitoring.md b/docs/de/monitoring.md new file mode 100644 index 0000000..74ca43c --- /dev/null +++ b/docs/de/monitoring.md @@ -0,0 +1,258 @@ +# Monitoring & Observability + +## Health Checks + +### HTTP Health Endpoint + +```bash +curl http://localhost:9470/health +``` + +Antwort: + +```json +{ + "status": "healthy", + "version": "0.1.0", + "uptime_seconds": 86400, + "checks": { + "storage": "ok", + "memory": "ok", + "connections": "ok" + } +} +``` + +### Readiness Probe + +```bash +curl http://localhost:9470/ready +``` + +Gibt `200 OK` zurück wenn der Server bereit ist Traffic anzunehmen, `503` während des Starts. + +## Metrics + +### Prometheus-kompatible Metrics + +```bash +curl http://localhost:9470/metrics +``` + +Beispielausgabe: + +``` +# HELP baradb_queries_total Total number of queries executed +# TYPE baradb_queries_total counter +baradb_queries_total 152340 + +# HELP baradb_queries_duration_seconds Query duration histogram +# TYPE baradb_queries_duration_seconds histogram +baradb_queries_duration_seconds_bucket{le="0.001"} 45000 +baradb_queries_duration_seconds_bucket{le="0.01"} 120000 +baradb_queries_duration_seconds_bucket{le="0.1"} 148000 + +# HELP baradb_storage_lsm_size_bytes LSM-Tree total size +# TYPE baradb_storage_lsm_size_bytes gauge +baradb_storage_lsm_size_bytes 2147483648 + +# HELP baradb_storage_sstables Number of SSTables +# TYPE baradb_storage_sstables gauge +baradb_storage_sstables 12 + +# HELP baradb_cache_hit_rate Page cache hit rate +# TYPE baradb_cache_hit_rate gauge +baradb_cache_hit_rate 0.94 + +# HELP baradb_active_connections Active client connections +# TYPE baradb_active_connections gauge +baradb_active_connections 42 + +# HELP baradb_txns_active Active transactions +# TYPE baradb_txns_active gauge +baradb_txns_active 7 + +# HELP baradb_txns_committed_total Total committed transactions +# TYPE baradb_txns_committed_total counter +baradb_txns_committed_total 89123 +``` + +### JSON Metrics + +```bash +curl http://localhost:9470/metrics?format=json +``` + +## Logging + +### Log-Level + +| Level | Beschreibung | +|-------|--------------| +| `debug` | Detaillierte interne Operationen | +| `info` | Normale Operationen | +| `warn` | Behebbare Probleme | +| `error` | Fehler die Aufmerksamkeit erfordern | + +### Strukturiertes JSON Logging + +```bash +BARADB_LOG_LEVEL=info \ +BARADB_LOG_FORMAT=json \ +BARADB_LOG_FILE=/var/log/baradb/baradb.log \ +./build/baradadb +``` + +Beispiel-Log-Eintrag: + +```json +{ + "timestamp": "2025-01-15T10:30:00.123Z", + "level": "info", + "component": "server", + "message": "Query executed", + "query": "SELECT * FROM users", + "duration_ms": 12, + "client_ip": "10.0.0.15" +} +``` + +### Textformat + +```bash +BARADB_LOG_FORMAT=text ./build/baradadb +``` + +Ausgabe: + +``` +2025-01-15T10:30:00.123Z [INFO] server: Query executed | query="SELECT * FROM users" duration_ms=12 +``` + +## Alerting-Regeln + +### Prometheus AlertManager + +```yaml +groups: + - name: baradb + rules: + - alert: BaraDBHighErrorRate + expr: rate(baradb_errors_total[5m]) > 0.1 + for: 5m + labels: + severity: critical + annotations: + summary: "BaraDB error rate is high" + + - alert: BaraDBLowCacheHitRate + expr: baradb_cache_hit_rate < 0.8 + for: 10m + labels: + severity: warning + annotations: + summary: "BaraDB cache hit rate below 80%" + + - alert: BaraDBHighConnections + expr: baradb_active_connections > 800 + for: 5m + labels: + severity: warning + annotations: + summary: "BaraDB connection count is high" + + - alert: BaraDBDown + expr: up{job="baradb"} == 0 + for: 1m + labels: + severity: critical + annotations: + summary: "BaraDB instance is down" +``` + +## Grafana Dashboard + +Dashboard ID `baradb-001` importieren oder das bereitgestellte JSON in `monitoring/grafana-dashboard.json` verwenden. + +Wichtige Panels: +- Queries pro Sekunde +- Query-Latenz Perzentile (p50, p95, p99) +- Speichergröße und SSTable-Anzahl +- Cache Hit Rate +- Aktive Verbindungen +- Transaktionsrate +- Fehlerrate + +## Distributed Monitoring + +### Cluster Metrics + +Für Raft-Cluster überwachen: + +```bash +curl http://node1:9470/metrics/cluster +``` + +```json +{ + "cluster_id": "baradb-cluster-1", + "nodes": [ + {"id": "node1", "role": "leader", "health": "healthy"}, + {"id": "node2", "role": "follower", "health": "healthy"}, + {"id": "node3", "role": "follower", "health": "healthy"} + ], + "raft_log_index": 15420, + "raft_commit_index": 15420, + "shards": 4, + "replication_lag_ms": 5 +} +``` + +## Performance Profiling + +### Eingebauter CPU Profiler + +```bash +curl -X POST http://localhost:9470/debug/pprof/cpu?seconds=30 > cpu.prof +``` + +### Memory Profiler + +```bash +curl http://localhost:9470/debug/pprof/heap > heap.prof +``` + +### Trace + +```bash +curl -X POST http://localhost:9470/debug/pprof/trace?seconds=5 > trace.out +``` + +## Log-Aggregation + +### Fluent Bit Konfiguration + +```ini +[INPUT] + Name tail + Path /var/log/baradb/baradb.log + Parser json + Tag baradb + +[OUTPUT] + Name elasticsearch + Match baradb + Host elasticsearch + Port 9200 + Index baradb-logs +``` + +## Troubleshooting mit Metrics + +| Symptom | Metrik | Aktion | +|---------|--------|--------| +| Langsame Abfragen | `baradb_queries_duration_seconds` | Cache Hit Rate prüfen, Indizes in Betracht ziehen | +| Hoher Speicherverbrauch | `process_resident_memory_bytes` | Memtable/Cache-Größen reduzieren | +| Speicher wächst | `baradb_storage_lsm_size_bytes` | Manuelle Compaction ausführen | +| Verbindungsfehler | `baradb_active_connections` | Connection Pool erhöhen oder Knoten hinzufügen | +| Replikations-Lag | `baradb_replication_lag_ms` | Netzwerk prüfen, Ressourcen erhöhen | diff --git a/docs/de/performance.md b/docs/de/performance.md new file mode 100644 index 0000000..d23267f --- /dev/null +++ b/docs/de/performance.md @@ -0,0 +1,174 @@ +# BaraDB Performance-Leitfaden + +## Benchmark-Methodik + +Alle Benchmarks wurden ausgeführt mit: +- **Compiler**: Nim 2.2.0 mit `-d:release --opt:speed` +- **CPU**: AMD Ryzen 9 5900X (12 Kerne / 24 Threads) +- **Memory**: 64 GB DDR4-3600 +- **Storage**: Samsung 980 Pro NVMe SSD +- **OS**: Ubuntu 24.04 LTS + +Die vollständige Benchmark-Suite ausführen: + +```bash +nim c -d:ssl -d:release -r benchmarks/bench_all.nim +``` + +## Storage Engine Benchmarks + +### LSM-Tree Key-Value + +| Metrik | Wert | +|--------|------| +| Write Throughput | ~580,000 ops/s | +| Read Throughput | ~720,000 ops/s | +| Durchschnittliche Write-Latenz | 1.7 µs | +| Durchschnittliche Read-Latenz | 1.4 µs | +| Testdatensatz | 100,000 Keys (16-Byte Keys, 64-Byte Values) | + +Der LSM-Tree verwendet eine 64MB MemTable, WAL fsync bei jedem Write und size-tiered +Compaction mit 6 Levels. + +### B-Tree Index + +| Metrik | Wert | +|--------|------| +| Insert Throughput | ~1,200,000 ops/s | +| Point Lookup Throughput | ~1,500,000 ops/s | +| Range Scan (1000 Keys) | ~0.3 ms | +| Baumhöhe (100K Keys) | 4 | + +B-Tree Knoten sind 4KB mit Copy-on-Write für MVCC-Kompatibilität. + +## Vector Engine Benchmarks + +### HNSW Index + +| Metrik | Wert | +|--------|------| +| Insert (dim=128) | ~45,000 vectors/s | +| Search top-10 (dim=128, n=10K) | ~2 ms | +| Search top-10 (dim=128, n=100K) | ~8 ms | +| Speicher pro Vektor (dim=128) | ~580 bytes | + +Parameter: `M=16`, `efConstruction=200`, `efSearch=64`. + +### SIMD Distanzfunktionen + +| Operation | dim=128 | dim=768 | dim=1536 | +|-----------|---------|---------|----------| +| Cosine Distance | 4.2M/s | 850K/s | 420K/s | +| L2 (Euclidean) | 4.5M/s | 920K/s | 450K/s | +| Dot Product | 4.8M/s | 980K/s | 480K/s | + +SIMD verwendet AVX2 256-Bit Vektoren mit Loop Unrolling. + +### Quantization + +| Methode | Genauigkeitsverlust | Speicherreduzierung | +|---------|--------------------|--------------------| +| Scalar 8-bit | <1% | 4× | +| Scalar 4-bit | ~3% | 8× | +| Product Quantization (PQ16) | ~5% | 16× | +| Binary | ~15% | 32× | + +## Full-Text Search Benchmarks + +| Metrik | Wert | +|--------|------| +| Index Throughput | ~320,000 docs/s | +| BM25 Search | ~28,000 queries/s | +| Fuzzy Search (distance=2) | ~850 queries/s | +| Wildcard Regex Search | ~4,200 queries/s | + +Testkorpus: 5 einzigartige Dokumente × 2,000 Wiederholungen (~50 Wörter/Dok). + +## Graph Engine Benchmarks + +| Operation | Throughput | Latenz | +|-----------|------------|--------| +| Knoten hinzufügen | ~2.5M ops/s | 0.4 µs | +| Kante hinzufügen | ~1.8M ops/s | 0.55 µs | +| BFS (1K Knoten, 5K Kanten) | ~12K Traversierungen/s | 83 µs | +| DFS (1K Knoten, 5K Kanten) | ~15K Traversierungen/s | 67 µs | +| Dijkstra kürzester Pfad | — | ~120 µs | +| PageRank (10 Iterationen) | ~450 Graphen/s | 2.2 ms | +| Louvain Community Detection | — | ~45 ms | + +## Protokoll-Benchmarks + +| Protokoll | Verbindungen | Queries/sec | Latenz p99 | +|-----------|--------------|-------------|------------| +| Binary (localhost) | 1 | 45,000 | 0.4 ms | +| Binary (localhost) | 100 | 380,000 | 1.2 ms | +| HTTP/REST | 1 | 12,000 | 2.1 ms | +| HTTP/REST | 100 | 95,000 | 5.8 ms | +| WebSocket | 1 | 18,000 | 1.8 ms | + +## Query Engine Benchmarks + +| Abfragetyp | Zeilen | Zeit | +|------------|--------|------| +| Simple SELECT | 100K | 12 ms | +| SELECT + WHERE | 100K | 18 ms | +| SELECT + ORDER BY | 100K | 35 ms | +| GROUP BY + Aggregates | 100K | 42 ms | +| INNER JOIN (1K × 1K) | 1M Ergebnis | 85 ms | +| CTE (2 Ebenen) | 100K | 28 ms | +| Subquery (EXISTS) | 100K | 22 ms | + +## Skalierungsverhalten + +### Vertikale Skalierung + +| Kerne | LSM Write | LSM Read | Vector Search | +|-------|-----------|----------|---------------| +| 1 | 580K | 720K | 2.0 ms | +| 4 | 1.9M | 2.6M | 1.1 ms | +| 8 | 3.4M | 4.8M | 0.7 ms | +| 16 | 5.8M | 7.2M | 0.5 ms | + +### Speicherverbrauch + +| Komponente | Basis-Speicher | Pro-Entity Overhead | +|------------|----------------|---------------------| +| LSM MemTable | 64 MB (fest) | ~1.2× Rohdaten | +| B-Tree | 8 MB (fest) | ~8 bytes/Key | +| HNSW Index | — | ~580 bytes/Vektor (dim=128) | +| Graph | — | ~32 bytes/Knoten, ~24 bytes/Kante | +| FTS Index | — | ~40% von Rohtext | +| Page Cache | 256 MB (konfigurierbar) | — | + +## Tuning-Leitfaden + +### Für Write-intensive Workloads + +```bash +export BARADB_MEMTABLE_SIZE_MB=256 +export BARADB_WAL_SYNC_INTERVAL_MS=10 +export BARADB_COMPACTION_INTERVAL_MS=30000 +``` + +### Für Read-intensive Workloads + +```bash +export BARADB_CACHE_SIZE_MB=1024 +export BARADB_BLOOM_BITS_PER_KEY=10 +export BARADB_COMPACTION_INTERVAL_MS=120000 +``` + +### Für Vector Search + +```bash +export BARADB_VECTOR_EF_CONSTRUCTION=200 +export BARADB_VECTOR_EF_SEARCH=128 +export BARADB_VECTOR_M=32 +``` + +### Für Graph Analytics + +```bash +export BARADB_GRAPH_PAGE_RANK_ITERATIONS=20 +export BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0 +``` diff --git a/docs/de/protocol.md b/docs/de/protocol.md new file mode 100644 index 0000000..47ebbf4 --- /dev/null +++ b/docs/de/protocol.md @@ -0,0 +1,240 @@ +# Protokoll-Referenz + +BaraDB unterstützt mehrere Protokolle für Client-Kommunikation: +- **Binär Wire Protokoll** — hochperformant, niedrige Latenz +- **HTTP/REST API** — sprachunabhängig, einfach zu debuggen +- **WebSocket** — Streaming und Pub/Sub + +--- + +## Binär Wire Protokoll + +Das Binärprotokoll verwendet Big-Endian-Kodierung für alle Multi-Byte-Werte. + +### Verbindungslebenszyklus + +``` +Client Server + | | + |─── TCP connect ──────────────>| + |<── TLS handshake (optional) ──| + |─── Auth message ─────────────>| + |<── Auth_OK / Error ───────────| + |─── Query message ────────────>| + |<── Data / Complete / Error ───| + |─── Close message ────────────>| + |<── TCP close ─────────────────| +``` + +### Nachrichtenformat + +Jede Nachricht beginnt mit einem 8-Byte-Header: + +``` +┌─────────────┬─────────────┬─────────────┬─────────────────────┐ +│ Length │ Type │ Sequence │ Payload │ +│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ +│ uint32 BE │ uint8 │ uint8 │ │ +└─────────────┴─────────────┴─────────────┴─────────────────────┘ +``` + +### Nachrichtentypen + +| Typ | ID | Richtung | Beschreibung | +|------|----|-----------|-------------| +| Query | 0x01 | C→S | Abfrage ausführen | +| Insert | 0x02 | C→S | Daten einfügen | +| Update | 0x03 | C→S | Daten aktualisieren | +| Delete | 0x04 | C→S | Daten löschen | +| Ready | 0x05 | S→C | Bereit für nächsten Befehl | +| Error | 0x06 | S→C | Fehlerantwort | +| Auth | 0x07 | C→S | Authentifizierungsanfrage | +| Batch | 0x08 | C→S | Batch-Operationen | +| Ping | 0x09 | C→S | Keepalive Ping | +| Data | 0x81 | S→C | Abfrageergebnis-Daten | +| Complete | 0x82 | S→C | Abfrage abgeschlossen | +| Auth_OK | 0x83 | S→C | Authentifizierung erfolgreich | +| Pong | 0x84 | S→C | Keepalive-Antwort | + +### Query-Nachrichten-Payload + +``` +┌──────────────┬──────────────┬────────────────────────────┐ +│ Result Format│ Query Length │ Query String │ +│ (1 byte) │ (4 bytes) │ (Query Length bytes) │ +│ 0x00=Binary │ uint32 BE │ UTF-8 │ +│ 0x01=JSON │ │ │ +│ 0x02=Text │ │ │ +└──────────────┴──────────────┴────────────────────────────┘ +``` + +### Data-Nachrichten-Payload + +``` +┌──────────────┬─────────────────────────────────────────────┐ +│ Column Count │ Column Definitions + Row Data │ +│ (2 bytes) │ │ +│ uint16 BE │ │ +└──────────────┴─────────────────────────────────────────────┘ +``` + +### Spaltendefinition + +``` +┌──────────────┬──────────────┬────────────────────────────┐ +│ Name Length │ Name │ Type │ +│ (2 bytes) │ (N bytes) │ (1 byte) │ +│ uint16 BE │ UTF-8 │ Siehe FieldKind-Tabelle │ +└──────────────┴──────────────┴────────────────────────────┘ +``` + +### Feldtypen + +| Typ | ID | Größe | Beschreibung | +|------|----|------|-------------| +| NULL | 0x00 | 0 | NULL-Wert | +| BOOL | 0x01 | 1 | true/false | +| INT8 | 0x02 | 1 | Signed 8-bit Integer | +| INT16 | 0x03 | 2 | Signed 16-bit Integer | +| INT32 | 0x04 | 4 | Signed 32-bit Integer | +| INT64 | 0x05 | 8 | Signed 64-bit Integer | +| FLOAT32 | 0x06 | 4 | IEEE 754 Single Precision (Big-Endian) | +| FLOAT64 | 0x07 | 8 | IEEE 754 Double Precision (Big-Endian) | +| STRING | 0x08 | variable | UTF-8 String (4-Byte Längenpräfix) | +| BYTES | 0x09 | variable | Raw Bytes (4-Byte Längenpräfix) | +| ARRAY | 0x0A | variable | Array von Werten | +| OBJECT | 0x0B | variable | Key-Value Objekt | +| VECTOR | 0x0C | variable | Float32 Array (4-Byte Längenpräfix, Big-Endian Floats) | + +### Fehler-Nachrichten-Payload + +``` +┌──────────────┬──────────────┬────────────────────────────┐ +│ Error Code │ Message Len │ Error Message │ +│ (4 bytes) │ (4 bytes) │ (Message Len bytes) │ +│ uint32 BE │ uint32 BE │ UTF-8 │ +└──────────────┴──────────────┴────────────────────────────┘ +``` + +### Beispiel: Raw TCP-Session + +```bash +# Verbinden +nc localhost 9472 + +# Senden: Auth-Anfrage (Token "mytoken") +# Header: length=15, type=0x07, seq=1 +# Payload: token length=7, token="mytoken" +printf '\x00\x00\x00\x0f\x07\x01\x00\x00\x00\x07mytoken' > /dev/tcp/localhost/9472 + +# Empfangen: Auth_OK +# \x00\x00\x00\x06\x83\x01 + +# Senden: Query "SELECT 1" +printf '\x00\x00\x00\x12\x01\x02\x00\x00\x00\x00\x08SELECT 1' > /dev/tcp/localhost/9472 + +# Empfangen: Data + Complete +``` + +--- + +## HTTP/REST API + +Basis-URL: `http://localhost:9470/api/v1` + +### Endpoints + +#### Health + +```http +GET /health +``` + +Antwort: +```json +{ + "status": "healthy", + "version": "0.1.0", + "uptime_seconds": 86400 +} +``` + +#### Ready + +```http +GET /ready +``` + +Gibt `200` zurück wenn bereit, `503` während des Starts. + +#### Query + +```http +POST /query +Content-Type: application/json +Authorization: Bearer + +{ + "query": "SELECT name, age FROM users WHERE age > 18", + "params": [], + "format": "json" +} +``` + +#### Batch + +```http +POST /batch +Content-Type: application/json + +{ + "queries": [ + "INSERT users { name := 'Alice', age := 30 }", + "INSERT users { name := 'Bob', age := 25 }" + ] +} +``` + +### HTTP-Statuscodes + +| Code | Bedeutung | +|------|----------| +| 200 | Erfolg | +| 400 | Bad request (Syntaxfehler) | +| 401 | Unauthorized (Auth erforderlich) | +| 403 | Forbidden (ungenügende Berechtigungen) | +| 404 | Not found (Tabelle/Typ existiert nicht) | +| 429 | Too many requests (Rate limitiert) | +| 500 | Internal server error | +| 503 | Service unavailable (wird gestartet) | + +--- + +## WebSocket-Protokoll + +URL: `ws://localhost:9471` + +### Frame-Format + +WebSocket Text-Frames enthalten JSON-Nachrichten: + +```json +{ + "id": 1, + "type": "query", + "query": "SELECT * FROM users" +} +``` + +### Nachrichtentypen + +| Typ | Richtung | Beschreibung | +|------|-----------|--------------| +| `query` | C→S | Abfrage ausführen | +| `subscribe` | C→S | Änderungen abonnieren | +| `unsubscribe` | C→S | Abonnement beenden | +| `ping` | C→S | Keepalive | +| `result` | S→C | Abfrageergebnis | +| `notification` | S→C | Änderungsbenachrichtigung | +| `error` | S→C | Fehler | +| `pong` | S→C | Keepalive-Antwort | diff --git a/docs/de/schema.md b/docs/de/schema.md new file mode 100644 index 0000000..6f0486e --- /dev/null +++ b/docs/de/schema.md @@ -0,0 +1,55 @@ +# Schema-System + +BaraDB verwendet ein Schema-first Design mit Typvererbung und automatischen Migrationen. + +## Typen definieren + +```nim +import barabadb/schema/schema + +var s = newSchema() + +let person = newType("Person") +person.addProperty("name", "str", required = true) +person.addProperty("age", "int32") +s.addType("default", person) +``` + +## Typvererbung + +```nim +let employee = newType("Employee") +employee.setBases(@["Person"]) +employee.addProperty("department", "str") +s.addType("default", employee) + +# Vererbung auflösen — Employee erhält name, age, department +let resolved = s.resolveInheritance(employee) +``` + +## Schema-Operationen + +### Diff + +Zwei Schemata vergleichen: + +```nim +let diff = s.diff(oldSchema, newSchema) +``` + +### Migrationen + +Schema-Änderungen werden verfolgt und können Migrationsskripte generieren. + +## Eigenschaftstypen + +| Typ | Beschreibung | +|------|-------------| +| `str` | String | +| `int32` | 32-Bit Integer | +| `int64` | 64-Bit Integer | +| `float32` | 32-Bit Float | +| `float64` | 64-Bit Float | +| `bool` | Boolean | +| `datetime` | Datums-/Zeitwert | +| `bytes` | Binärdaten | diff --git a/docs/de/security.md b/docs/de/security.md new file mode 100644 index 0000000..ee5b484 --- /dev/null +++ b/docs/de/security.md @@ -0,0 +1,184 @@ +# Sicherheitsleitfaden + +## TLS/SSL-Verschlüsselung + +BaraDB unterstützt TLS 1.3 für alle Protokolle (Binary, HTTP, WebSocket). Wenn kein +Zertifikat bereitgestellt wird, generiert der Server automatisch ein selbstsigniertes Zertifikat +beim Start für Zero-Configuration-Verschlüsselung. + +### Eigene Zertifikate verwenden + +```bash +# Vorhandene Zertifikate bereitstellen +BARADB_TLS_ENABLED=true \ +BARADB_CERT_FILE=/etc/baradb/server.crt \ +BARADB_KEY_FILE=/etc/baradb/server.key \ +./build/baradadb +``` + +### Selbstsignierte Zertifikate generieren + +```bash +openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ + -days 365 -nodes -subj "/CN=localhost" +``` + +### Let's Encrypt (Production) + +Certbot verwenden und BaraDB auf die generierten Dateien zeigen: + +```bash +sudo certbot certonly --standalone -d db.example.com + +BARADB_CERT_FILE=/etc/letsencrypt/live/db.example.com/fullchain.pem \ +BARADB_KEY_FILE=/etc/letsencrypt/live/db.example.com/privkey.pem \ +./build/baradadb +``` + +## Authentifizierung + +### JWT-basierte Authentifizierung + +BaraDB verwendet JWT (JSON Web Tokens) mit HMAC-SHA256-Signatur. + +#### Authentifizierung aktivieren + +```bash +BARADB_AUTH_ENABLED=true \ +BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ +./build/baradadb +``` + +#### Tokens erstellen + +```nim +import barabadb/protocol/auth + +var am = newAuthManager("your-secret-key") +let token = am.createToken(JWTClaims( + sub: "user1", + role: "admin", + exp: getTime() + 24.hours +)) +``` + +#### Rollenbasierte Zugriffskontrolle + +| Rolle | Berechtigungen | +|------|---------------| +| `admin` | Voller Zugriff | +| `write` | Lesen + Schreiben | +| `read` | Nur Lesen | +| `monitor` | Nur Metrics und Health | + +#### Tokens verwenden + +```bash +curl -H "Authorization: Bearer $TOKEN" \ + http://localhost:9470/api/query \ + -d '{"query": "SELECT * FROM users"}' +``` + +## Rate Limiting + +Token-Bucket Rate Limiting verhindert Missbrauch: + +```nim +import barabadb/protocol/ratelimit + +var rl = newRateLimiter( + rlaTokenBucket, + globalRate = 10000, # 10K req/s global + perClientRate = 1000, # 1K req/s pro IP/Token + burstSize = 100 # 100 req Burst erlauben +) + +if not rl.allowRequest("client-ip"): + return error("Rate limit exceeded") +``` + +## Netzwerksicherheit + +### Bind-Adresse + +Standardmäßig bindet BaraDB an `127.0.0.1` (nur Localhost). Für Production: + +```bash +# An alle Interfaces binden (hinter Firewall oder Reverse Proxy) +BARADB_ADDRESS=0.0.0.0 ./build/baradadb + +# An spezifisches internes Interface binden +BARADB_ADDRESS=10.0.0.5 ./build/baradadb +``` + +### Firewall-Regeln + +```bash +# Nur Application-Server erlauben +sudo ufw allow from 10.0.0.0/8 to any port 9472 +sudo ufw allow from 10.0.0.0/8 to any port 9470 + +# Externen Zugriff auf Management-Ports blockieren +sudo ufw deny 9471 # WebSocket (nur für internen Gebrauch) +``` + +## Datenverschlüsselung at Rest + +### OS-Level-Verschlüsselung + +LUKS für Vollständige-Festplatten-Verschlüsselung verwenden: + +```bash +cryptsetup luksFormat /dev/nvme0n1p2 +cryptsetup open /dev/nvme0n1p2 baradb-crypt +mkfs.ext4 /dev/mapper/baradb-crypt +mount /dev/mapper/baradb-crypt /var/lib/baradb +``` + +### Applikations-Level-Verschlüsselung + +BaraDB unterstützt transparente Verschlüsselung von SSTable-Dateien: + +```bash +BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \ +./build/baradadb +``` + +## Audit Logging + +Alle Abfragen und administrativen Aktionen werden geloggt: + +```json +{ + "timestamp": "2025-01-15T10:30:00Z", + "level": "info", + "event": "query_executed", + "client_ip": "10.0.0.15", + "user": "app_user", + "query": "SELECT * FROM users WHERE id = ?", + "duration_ms": 12, + "rows_returned": 1 +} +``` + +Audit Logging aktivieren: + +```bash +BARADB_LOG_LEVEL=info \ +BARADB_LOG_FORMAT=json \ +BARADB_LOG_FILE=/var/log/baradb/audit.log \ +./build/baradadb +``` + +## Sicherheits-Checkliste + +- [ ] Standard-JWT-Geheimnis ändern +- [ ] TLS mit gültigen Zertifikaten aktivieren +- [ ] An spezifische Interfaces binden +- [ ] Authentifizierung in Production aktivieren +- [ ] Rate Limiting konfigurieren +- [ ] Audit Logging aktivieren +- [ ] Daten at Rest verschlüsseln (LUKS oder App-Level) +- [ ] BaraDB als Non-Root-Benutzer ausführen +- [ ] Firewall-Regeln restriktiv halten +- [ ] JWT-Geheimnisse regelmäßig rotieren diff --git a/docs/de/storage.md b/docs/de/storage.md new file mode 100644 index 0000000..79df0ad --- /dev/null +++ b/docs/de/storage.md @@ -0,0 +1,78 @@ +# Speicher-Engines + +BaraDB bietet mehrere Speicher-Engines, optimiert für verschiedene Zugriffsmuster. + +## LSM-Tree (Key-Value) + +Die primäre Speicher-Engine mit write-optimierter Append-only Log-Struktur. + +### Verwendung + +```nim +import barabadb/storage/lsm + +var db = newLSMTree("./data") +db.put("key1", cast[seq[byte]]("value1")) +let (found, value) = db.get("key1") +db.close() +``` + +### Komponenten + +- **MemTable**: In-Memory sortierter Puffer +- **WAL**: Write-Ahead Log für Dauerhaftigkeit +- **SSTable**: Sortierte String-Tabellen auf Disk +- **Bloom-Filter**: Probabilistische Mengenmitgliedschaft +- **Compaction**: Size-tiered Strategie mit Level-Management +- **Page-Cache**: LRU-Cache mit Trefferraten-Verfolgung + +## B-Tree Index + +Geordneter Index für Bereichsabfragen und Point-Lookups. + +### Verwendung + +```nim +import barabadb/storage/btree + +var btree = newBTreeIndex[string, string]() +btree.insert("key1", "value1") +let values = btree.get("key1") +let range = btree.scan("key_a", "key_z") +``` + +## Write-Ahead Log (WAL) + +Sichert Dauerhaftigkeit von Schreiboperationen. + +```nim +import barabadb/storage/wal + +var wal = newWAL("./wal") +wal.append("txn1", "SET key1 value1") +wal.flush() +``` + +## Bloom-Filter + +Probabilistische Datenstruktur für schnelle negative Lookups. + +```nim +import barabadb/storage/bloom + +var filter = newBloomFilter(10000, 0.01) +filter.add("key1") +if filter.mightContain("key1"): + echo "possibly exists" +``` + +## Memory-mapped I/O + +Effizienter Dateizugriff mittels mmap. + +```nim +import barabadb/storage/mmap + +var mapped = mmapFile("./data/file.dat") +let data = mapped.read(0, 100) +``` diff --git a/docs/de/transactions.md b/docs/de/transactions.md new file mode 100644 index 0000000..4fb5ab3 --- /dev/null +++ b/docs/de/transactions.md @@ -0,0 +1,78 @@ +# Transaktionen & MVCC + +MVCC (Multi-Version Concurrency Control) mit Snapshot-Isolation und Deadlock-Erkennung. + +## Verwendung + +```nim +import barabadb/core/mvcc + +var tm = newTxnManager() +let txn = tm.beginTxn() + +# Schreiboperationen +discard tm.write(txn, "key1", cast[seq[byte]]("value1")) +discard tm.write(txn, "key2", cast[seq[byte]]("value2")) + +# Savepoint +tm.savepoint(txn) +discard tm.write(txn, "key3", cast[seq[byte]]("value3")) +discard tm.rollbackToSavepoint(txn) # rückgängig machen key3 + +# Commit +discard tm.commit(txn) +``` + +## Transaktionsisolation + +BaraDB verwendet **Snapshot-Isolation**: +- Leser blockieren keine Schreiber +- Schreiber blockieren keine Leser +- Jede Transaktion sieht einen konsistenten Snapshot + +## Deadlock-Erkennung + +```nim +import barabadb/core/deadlock + +var detector = newDeadlockDetector() +if detector.detectCycle(txn1, txn2): + echo "Deadlock erkannt!" +``` + +## Write-Ahead Log + +```nim +import barabadb/storage/wal + +var wal = newWAL("./wal") +wal.append(txnId, "SET key value") +wal.flush() +``` + +## Savepoints + +Verschachtelte Transaktions-Savepoints: + +```nim +tm.savepoint(txn, "sp1") +# ... Operationen ... +tm.rollbackToSavepoint(txn, "sp1") +``` + +## Formale Verifikation + +Das MVCC / Snapshot-Isolation Protokoll ist formal in TLA+ spezifiziert: + +- **Spec:** `formal-verification/mvcc.tla` +- **Verifizierte Eigenschaften:** + - `NoDirtyReads` — Transaktionen lesen niemals nicht-committete Daten + - `ReadOwnWrites` — Transaktionen sehen immer ihre eigenen Schreiboperationen + - `WriteWriteConflict` — First-committer-wins (keine zwei committete Transaktionen schreiben denselben Schlüssel) + +Lokale TLC-Ausführung: + +```bash +cd formal-verification +java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla +``` diff --git a/docs/de/troubleshooting.md b/docs/de/troubleshooting.md new file mode 100644 index 0000000..c3dcb67 --- /dev/null +++ b/docs/de/troubleshooting.md @@ -0,0 +1,335 @@ +# Fehlerbehebungsleitfaden + +## Installationsprobleme + +### Nim nicht gefunden + +``` +im: command not found +``` + +**Lösung:** + +```bash +# Linux/macOS +curl https://nim-lang.org/choosenim/init.sh -sSf | sh + +# Zu PATH hinzufügen +echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc +source ~/.bashrc +``` + +### SSL-Kompilierungsfehler + +``` +Error: BaraDB requires SSL support. Compile with -d:ssl +``` + +**Lösung:** Immer mit `-d:ssl` kompilieren: + +```bash +nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim +``` + +### Fehlende Abhängigkeiten + +``` +Error: cannot open file: hunos +``` + +**Lösung:** + +```bash +nimble install -d -y +``` + +## Laufzeitprobleme + +### Port bereits in Verwendung + +``` +Error: unhandled exception: Address already in use [OSError] +``` + +**Lösung 1:** Port ändern: + +```bash +BARADB_PORT=5433 ./build/baradadb +``` + +**Lösung 2:** Bestehenden Prozess beenden: + +```bash +lsof -ti:9472 | xargs kill -9 +# oder +fuser -k 9472/tcp +``` + +### Permission Denied auf Datenverzeichnis + +``` +Error: cannot create directory: Permission denied +``` + +**Lösung:** + +```bash +mkdir -p ./data +chmod 755 ./data +# Oder anderes Verzeichnis verwenden +BARADB_DATA_DIR=/tmp/baradb_data ./build/baradadb +``` + +### Out of Memory + +``` +Error: out of memory +``` + +**Lösung:** Speicherverbrauch reduzieren: + +```bash +BARADB_MEMTABLE_SIZE_MB=32 \ +BARADB_CACHE_SIZE_MB=128 \ +BARADB_VECTOR_EF_CONSTRUCTION=100 \ +./build/baradadb +``` + +### Disk Full + +``` +Error: No space left on device +``` + +**Lösung:** + +```bash +# Disk-Nutzung prüfen +df -h + +# Compaction auslösen um Platz freizugeben +curl -X POST http://localhost:9470/api/admin/compact + +# Oder manuell +./build/baradadb --compact +``` + +## Abfrageprobleme + +### Syntaxfehler + +``` +Error: Syntax error at position 15: unexpected token +``` + +**Lösung:** Abfragesyntax prüfen: + +```sql +-- Korrekt +SELECT name, age FROM users WHERE age > 18; + +-- Inkorrekt (fehlendes Komma) +SELECT name age FROM users WHERE age > 18; +``` + +### Tabelle nicht gefunden + +``` +Error: Table 'users' does not exist +``` + +**Lösung:** Zuerst Schema erstellen: + +```sql +CREATE TYPE User { + name: str, + age: int32 +}; +``` + +### Typ-Mismatch + +``` +Error: Cannot compare int32 with str +``` + +**Lösung:** Korrekte Typen verwenden: + +```sql +-- Korrekt +SELECT * FROM users WHERE age > 18; + +-- Inkorrekt +SELECT * FROM users WHERE age > '18'; +``` + +### Timeout + +``` +Error: Query execution timeout +``` + +**Lösung:** LIMIT hinzufügen oder optimieren: + +```sql +-- Limit hinzufügen +SELECT * FROM large_table LIMIT 1000; + +-- Index verwenden +SELECT * FROM users WHERE id = 123; +``` + +## Verbindungsprobleme + +### Connection Refused + +``` +Connection refused: localhost:9472 +``` + +**Lösung:** + +```bash +# Prüfen ob Server läuft +ps aux | grep baradadb + +# Server starten +./build/baradadb + +# Firewall prüfen +sudo ufw status +sudo ufw allow 9472 +``` + +### Authentifizierung fehlgeschlagen + +``` +Error: Authentication failed +``` + +**Lösung:** + +```bash +# Prüfen ob JWT-Geheimnis übereinstimmt +BARADB_AUTH_ENABLED=true \ +BARADB_JWT_SECRET="correct-secret" \ +./build/baradadb +``` + +## Performance-Probleme + +### Langsame Abfragen + +**Diagnose:** + +```bash +# Abfrageplan prüfen +curl -X POST http://localhost:9470/api/explain \ + -d '{"query": "SELECT * FROM large_table"}' +``` + +**Lösungen:** + +1. Indizes hinzufügen: +```sql +CREATE INDEX idx_users_name ON users(name); +``` + +2. LIMIT verwenden: +```sql +SELECT * FROM users LIMIT 100; +``` + +3. Cache erhöhen: +```bash +BARADB_CACHE_SIZE_MB=1024 ./build/baradadb +``` + +### Hohe CPU-Nutzung + +**Ursachen:** +- Compaction läuft +- Große Vektor-Suche ohne HNSW +- Komplexe Graph-Traversierung + +**Lösungen:** + +```bash +# Compaction-Intervall anpassen +BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb + +# Approximative Vektor-Suche verwenden +SELECT /*+ APPROXIMATE */ * FROM vectors +ORDER BY cosine_distance(embedding, [...]) +LIMIT 10; +``` + +## Cluster-Probleme + +### Raft Split-Brain + +``` +Warning: Multiple leaders detected +``` + +**Lösung:** Ungerade Anzahl von Knoten sicherstellen (3, 5, 7). Minority-Partition neu starten. + +### Replikations-Lag + +``` +Warning: Replication lag > 10s +``` + +**Lösung:** + +```bash +# Netzwerk-Latenz prüfen +ping replica-node + +# Replikations-Threads erhöhen +BARADB_REPLICATION_THREADS=4 ./build/baradadb + +# Auf Async-Replikation umschalten +BARADB_REPLICATION_MODE=async +``` + +## Datenkorruption + +### Prüfsummen-Mismatch + +``` +Error: SSTable checksum mismatch +``` + +**Lösung:** + +```bash +# Korrupte SSTable entfernen (Daten werden aus WAL wiederhergestellt) +rm ./data/sstables/corrupted.sst + +# Neustarten und wiederherstellen +./build/baradadb --recover +``` + +## Debug-Modus + +Debug-Logging für detaillierte Diagnostik aktivieren: + +```bash +BARADB_LOG_LEVEL=debug \ +BARADB_LOG_FILE=/tmp/baradb_debug.log \ +./build/baradadb +``` + +## Hilfe erhalten + +Wenn das Problem weiterhin besteht: + +1. Logs prüfen: `tail -f /var/log/baradb/baradb.log` +2. Metrics prüfen: `curl http://localhost:9470/metrics` +3. Diagnostik ausführen: `./build/baradadb --diagnose` +4. Issue öffnen mit: + - BaraDB Version (`./build/baradadb --version`) + - OS und Architektur + - Relevante Log-Auszüge + - Schritte zur Reproduktion diff --git a/docs/de/udf.md b/docs/de/udf.md new file mode 100644 index 0000000..a2ece38 --- /dev/null +++ b/docs/de/udf.md @@ -0,0 +1,56 @@ +# Benutzerdefinierte Funktionen + +BaraQL mit benutzerdefinierten Funktionen erweitern. + +## Verwendung + +```nim +import barabadb/query/udf + +var reg = newUDFRegistry() + +# Standard-Bibliothek registrieren +reg.registerStdlib() # abs, sqrt, pow, lower, upper, len, trim, substr, toString, toInt + +# Benutzerdefinierte Funktion +reg.register("greet", @[UDFParam(name: "name", typeName: "str")], + "str", proc(args: seq[Value]): Value = + return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) +``` + +## Standard-Bibliotheksfunktionen + +| Funktion | Beschreibung | Beispiel | +|----------|-------------|---------| +| `abs(n)` | Absoluter Wert | `abs(-5)` → 5 | +| `sqrt(n)` | Quadratwurzel | `sqrt(16)` → 4 | +| `pow(n, e)` | Potenz | `pow(2, 3)` → 8 | +| `lower(s)` | Kleinbuchstaben | `lower('ABC')` → 'abc' | +| `upper(s)` | Großbuchstaben | `upper('abc')` → 'ABC' | +| `len(s)` | Länge | `len('hello')` → 5 | +| `trim(s)` | Leerzeichen trimmen | `trim(' hello ')` → 'hello' | +| `substr(s, start, len)` | Substring | `substr('hello', 0, 3)` → 'hel' | +| `toString(n)` | In String konvertieren | `toString(123)` → '123' | +| `toInt(s)` | In Integer konvertieren | `toInt('123')` → 123 | + +## Funktionsregistrierung + +```nim +reg.register( + name: "my_function", + params: @[ + UDFParam(name: "arg1", typeName: "str"), + UDFParam(name: "arg2", typeName: "int32") + ], + returnType: "str", + body: proc(args: seq[Value]): Value = + # Implementierung + result = Value(kind: vkString, strVal: "") +) +``` + +## UDFs in Abfragen verwenden + +```sql +SELECT greet(name) FROM users; +``` diff --git a/docs/fa/mcp.md b/docs/fa/mcp.md new file mode 100644 index 0000000..5e737ad --- /dev/null +++ b/docs/fa/mcp.md @@ -0,0 +1,109 @@ +# سرور MCP (Model Context Protocol) + +BaraDB شامل یک سرور MCP داخلی است که به عوامل هوش مصنوعی (Claude، Cursor و غیره) امکان تعامل مستقیم با پایگاه داده را می‌دهد. + +## شروع سریع + +```bash +./build/baramcp --data-dir ./data +``` + +در حالت STDIO شروع می‌شود و پیام‌های JSON-RPC 2.0 را در stdin قبول می‌کند. + +## ابزارهای موجود + +### 1. `query` — اجرای SQL + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +پرس‌وجوهای پارامتری با `?` placeholders. پشتیبانی multi-tenant از طریق `tenant_id` و `user_id`. + +### 2. `vector_search` — جستجوی معنایی + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +معیارها: `cosine`، `euclidean`، `dot_product`، `manhattan`. + +### 3. `schema_inspect` — بررسی طرحواره + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +جداول، ستون‌ها، انواع، کلیدهای اصلی، کلیدهای خارجی، شاخص‌ها و سیاست‌های RLS را برمی‌گرداند. + +## پیکربندی Claude Desktop + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## پیکربندی Cursor + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## جداسازی Multi-Tenant + +هر درخواست MCP می‌تواند شامل `tenant_id` و `user_id` باشد که به عنوان متغیرهای session تنظیم می‌شوند: +- `app.tenant_id` — برای فیلتر RLS +- `app.user_id` — برای referencهای `current_user` + +سیاست‌های RLS به طور خودکار داده‌ها را بر اساس این متغیرها فیلتر می‌کنند. + +## پروتکل JSON-RPC 2.0 + +سرور از JSON-RPC 2.0 از طریق STDIO استفاده می‌کند: + +```json +// درخواست +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// پاسخ +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +``` diff --git a/docs/ru/mcp.md b/docs/ru/mcp.md new file mode 100644 index 0000000..17a467c --- /dev/null +++ b/docs/ru/mcp.md @@ -0,0 +1,109 @@ +# MCP Сервер (Model Context Protocol) + +BaraDB включает встроенный MCP-сервер, который позволяет агентам AI (Claude, Cursor и т.д.) взаимодействовать с базой данных напрямую. + +## Быстрый старт + +```bash +./build/baramcp --data-dir ./data +``` + +Запускается в режиме STDIO, принимая сообщения JSON-RPC 2.0 на stdin. + +## Доступные инструменты + +### 1. `query` — Выполнение SQL + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +Параметризованные запросы с `?` placeholders. Multi-tenant поддержка через `tenant_id` и `user_id`. + +### 2. `vector_search` — Семантический поиск + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +Метрики: `cosine`, `euclidean`, `dot_product`, `manhattan`. + +### 3. `schema_inspect` — Исследование схемы + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +Возвращает таблицы, столбцы, типы, первичные ключи, внешние ключи, индексы и RLS-политики. + +## Конфигурация в Claude Desktop + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## Конфигурация в Cursor + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## Multi-Tenant изоляция + +Каждый MCP-запрос может включать `tenant_id` и `user_id`, установленные как переменные сессии: +- `app.tenant_id` — для RLS-фильтрации +- `app.user_id` — для ссылок `current_user` + +RLS-политики автоматически фильтруют данные на основе этих переменных. + +## Протокол JSON-RPC 2.0 + +Сервер использует JSON-RPC 2.0 через STDIO: + +```json +// Запрос +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// Ответ +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +``` diff --git a/docs/tr/mcp.md b/docs/tr/mcp.md new file mode 100644 index 0000000..c4f934c --- /dev/null +++ b/docs/tr/mcp.md @@ -0,0 +1,109 @@ +# MCP Sunucusu (Model Context Protocol) + +BaraDB, AI ajanlarının (Claude, Cursor vb.) veritabanıyla doğrudan etkileşim kurmasını sağlayan yerleşik bir MCP sunucusu içerir. + +## Hızlı Başlangıç + +```bash +./build/baramcp --data-dir ./data +``` + +STDIO modunda başlar, stdin'de JSON-RPC 2.0 mesajlarını kabul eder. + +## Mevcut Araçlar + +### 1. `query` — SQL Yürütme + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +`?` placeholders kullanarak parametreli sorgular. `tenant_id` ve `user_id` ile multi-tenant desteği. + +### 2. `vector_search` — Anlamsal Arama + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +Metrikler: `cosine`, `euclidean`, `dot_product`, `manhattan`. + +### 3. `schema_inspect` — Şema Keşfi + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +Tabloları, sütunları, tipleri, birincil anahtarları, yabancı anahtarları, indeksleri ve RLS politikalarını döndürür. + +## Claude Desktop Yapılandırması + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## Cursor Yapılandırması + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## Multi-Tenant İzolasyonu + +Her MCP isteği `tenant_id` ve `user_id` içerebilir, bunlar session değişkenleri olarak ayarlanır: +- `app.tenant_id` — RLS filtreleme için +- `app.user_id` — `current_user` referansları için + +RLS politikaları bu değişkenlere göre verileri otomatik olarak filtreler. + +## JSON-RPC 2.0 Protokolü + +Sunucu STDIO üzerinden JSON-RPC 2.0 kullanır: + +```json +// İstek +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// Yanıt +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +``` diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md new file mode 100644 index 0000000..e49f45f --- /dev/null +++ b/docs/zh/mcp.md @@ -0,0 +1,109 @@ +# MCP 服务器 (Model Context Protocol) + +BaraDB 包含一个内置 MCP 服务器，使 AI 代理（Claude、Cursor 等）能够直接与数据库交互。 + +## 快速入门 + +```bash +./build/baramcp --data-dir ./data +``` + +以 STDIO 模式启动，在 stdin 上接受 JSON-RPC 2.0 消息。 + +## 可用工具 + +### 1. `query` — SQL 执行 + +```json +{ + "name": "query", + "arguments": { + "sql": "SELECT * FROM users WHERE age > ?", + "params": [25], + "tenant_id": "company-a", + "user_id": "alice" + } +} +``` + +使用 `?` 占位符的参数化查询。通过 `tenant_id` 和 `user_id` 实现多租户支持。 + +### 2. `vector_search` — 语义搜索 + +```json +{ + "name": "vector_search", + "arguments": { + "table": "docs", + "column": "embedding", + "query_vector": [0.1, 0.2, 0.3], + "k": 5, + "metric": "cosine", + "filter_column": "category", + "filter_value": "news", + "tenant_id": "company-a" + } +} +``` + +度量：`cosine`、`euclidean`、`dot_product`、`manhattan`。 + +### 3. `schema_inspect` — Schema 探索 + +```json +{ + "name": "schema_inspect", + "arguments": { + "table": "users", + "tenant_id": "company-a" + } +} +``` + +返回表、列、类型、主键、外键、索引和 RLS 策略。 + +## Claude Desktop 配置 + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "/path/to/data"] + } + } +} +``` + +## Cursor 配置 + +```json +{ + "mcpServers": { + "baradb": { + "command": "/path/to/build/baramcp", + "args": ["--data-dir", "~/.baradb/data"] + } + } +} +``` + +## 多租户隔离 + +每个 MCP 请求都可以包含 `tenant_id` 和 `user_id`，它们被设置为会话变量： +- `app.tenant_id` — 用于 RLS 过滤 +- `app.user_id` — 用于 `current_user` 引用 + +RLS 策略根据这些变量自动过滤数据。 + +## JSON-RPC 2.0 协议 + +服务器通过 STDIO 使用 JSON-RPC 2.0： + +```json +// 请求 +{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} + +// 响应 +{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} +```