From a526a3aef9795881367ec3b728d3dd10a406840e Mon Sep 17 00:00:00 2001 From: dimgigov Date: Thu, 21 May 2026 09:44:17 +0300 Subject: [PATCH] docs: remove non-English/Bulgarian language docs, fix links Remove ar, de, fa, ru, tr, zh documentation folders. Update docs/index.md and docs/bg/index.md to only list en/bg. Update README badge from 7 to 2 languages. Update changelog entry for Bulgarian docs. --- README.md | 6 +- docs/ar/api-binary.md | 62 ---- docs/ar/api-http.md | 62 ---- docs/ar/api-websocket.md | 78 ----- docs/ar/architecture.md | 102 ------- docs/ar/backup.md | 82 ----- docs/ar/baraql.md | 268 ----------------- docs/ar/btree.md | 26 -- docs/ar/changelog.md | 76 ----- docs/ar/clients.md | 66 ---- docs/ar/columnar.md | 50 ---- docs/ar/configuration.md | 96 ------ docs/ar/crossmodal.md | 48 --- docs/ar/deployment.md | 68 ----- docs/ar/distributed.md | 73 ----- docs/ar/docker.md | 78 ----- docs/ar/fts.md | 47 --- docs/ar/graph.md | 42 --- docs/ar/index.md | 59 ---- docs/ar/installation.md | 308 ------------------- docs/ar/lsm.md | 48 --- docs/ar/mcp.md | 109 ------- docs/ar/monitoring.md | 84 ------ docs/ar/performance.md | 68 ----- docs/ar/protocol.md | 67 ----- docs/ar/quickstart.md | 99 ------ docs/ar/schema.md | 46 --- docs/ar/security.md | 76 ----- docs/ar/storage.md | 67 ----- docs/ar/transactions.md | 47 --- docs/ar/troubleshooting.md | 81 ----- docs/ar/udf.md | 47 --- docs/ar/vector.md | 65 ---- docs/bg/index.md | 8 +- docs/de/api-binary.md | 74 ----- docs/de/api-http.md | 91 ------ docs/de/api-websocket.md | 120 -------- docs/de/architecture.md | 152 ---------- docs/de/backup.md | 199 ------------- docs/de/baraql.md | 114 ------- docs/de/btree.md | 38 --- docs/de/changelog.md | 247 --------------- docs/de/clients.md | 285 ------------------ docs/de/columnar.md | 58 ---- docs/de/configuration.md | 217 -------------- docs/de/crossmodal.md | 218 -------------- docs/de/deployment.md | 247 --------------- docs/de/distributed.md | 110 ------- docs/de/docker.md | 191 ------------ docs/de/fts.md | 87 ------ docs/de/graph.md | 145 --------- docs/de/index.md | 64 ---- docs/de/installation.md | 57 ---- docs/de/lsm.md | 64 ---- docs/de/mcp.md | 108 ------- docs/de/monitoring.md | 258 ---------------- docs/de/performance.md | 174 ----------- docs/de/protocol.md | 240 --------------- docs/de/quickstart.md | 134 --------- docs/de/schema.md | 55 ---- docs/de/security.md | 184 ------------ docs/de/storage.md | 78 ----- docs/de/transactions.md | 78 ----- docs/de/troubleshooting.md | 335 --------------------- docs/de/udf.md | 56 ---- docs/de/vector.md | 129 -------- docs/en/changelog.md | 2 +- docs/fa/api-binary.md | 62 ---- docs/fa/api-http.md | 62 ---- docs/fa/api-websocket.md | 67 ----- docs/fa/architecture.md | 197 ------------ docs/fa/backup.md | 81 ----- docs/fa/baraql.md | 597 ------------------------------------- docs/fa/btree.md | 25 -- docs/fa/changelog.md | 70 ----- docs/fa/clients.md | 66 ---- docs/fa/columnar.md | 50 ---- docs/fa/configuration.md | 94 ------ docs/fa/crossmodal.md | 40 --- docs/fa/deployment.md | 249 ---------------- docs/fa/distributed.md | 82 ----- docs/fa/docker.md | 113 ------- docs/fa/fts.md | 47 --- docs/fa/graph.md | 42 --- docs/fa/index.md | 59 ---- docs/fa/installation.md | 309 ------------------- docs/fa/lsm.md | 48 --- docs/fa/mcp.md | 109 ------- docs/fa/monitoring.md | 78 ----- docs/fa/performance.md | 62 ---- docs/fa/protocol.md | 67 ----- docs/fa/quickstart.md | 134 --------- docs/fa/schema.md | 46 --- docs/fa/security.md | 120 -------- docs/fa/storage.md | 78 ----- docs/fa/transactions.md | 67 ----- docs/fa/troubleshooting.md | 87 ------ docs/fa/udf.md | 46 --- docs/fa/vector.md | 57 ---- docs/index.md | 8 +- docs/ru/api-binary.md | 71 ----- docs/ru/api-http.md | 83 ------ docs/ru/api-websocket.md | 80 ----- docs/ru/architecture.md | 197 ------------ docs/ru/backup.md | 120 -------- docs/ru/baraql.md | 597 ------------------------------------- docs/ru/btree.md | 34 --- docs/ru/changelog.md | 78 ----- docs/ru/clients.md | 82 ----- docs/ru/columnar.md | 58 ---- docs/ru/configuration.md | 217 -------------- docs/ru/crossmodal.md | 63 ---- docs/ru/deployment.md | 44 --- docs/ru/distributed.md | 108 ------- docs/ru/docker.md | 189 ------------ docs/ru/fts.md | 62 ---- docs/ru/graph.md | 51 ---- docs/ru/index.md | 59 ---- docs/ru/installation.md | 309 ------------------- docs/ru/lsm.md | 61 ---- docs/ru/mcp.md | 109 ------- docs/ru/monitoring.md | 148 --------- docs/ru/performance.md | 95 ------ docs/ru/protocol.md | 87 ------ docs/ru/quickstart.md | 134 --------- docs/ru/schema.md | 52 ---- docs/ru/security.md | 210 ------------- docs/ru/storage.md | 78 ----- docs/ru/transactions.md | 78 ----- docs/ru/troubleshooting.md | 168 ----------- docs/ru/udf.md | 51 ---- docs/ru/vector.md | 71 ----- docs/tr/api-binary.md | 62 ---- docs/tr/api-http.md | 62 ---- docs/tr/api-websocket.md | 78 ----- docs/tr/architecture.md | 102 ------- docs/tr/backup.md | 82 ----- docs/tr/baraql.md | 269 ----------------- docs/tr/btree.md | 26 -- docs/tr/changelog.md | 76 ----- docs/tr/clients.md | 66 ---- docs/tr/columnar.md | 50 ---- docs/tr/configuration.md | 106 ------- docs/tr/crossmodal.md | 48 --- docs/tr/deployment.md | 68 ----- docs/tr/distributed.md | 73 ----- docs/tr/docker.md | 78 ----- docs/tr/fts.md | 47 --- docs/tr/graph.md | 42 --- docs/tr/index.md | 59 ---- docs/tr/installation.md | 308 ------------------- docs/tr/lsm.md | 48 --- docs/tr/mcp.md | 109 ------- docs/tr/monitoring.md | 84 ------ docs/tr/performance.md | 68 ----- docs/tr/protocol.md | 67 ----- docs/tr/quickstart.md | 99 ------ docs/tr/schema.md | 46 --- docs/tr/security.md | 76 ----- docs/tr/storage.md | 67 ----- docs/tr/transactions.md | 47 --- docs/tr/troubleshooting.md | 81 ----- docs/tr/udf.md | 47 --- docs/tr/vector.md | 65 ---- docs/zh/api-binary.md | 62 ---- docs/zh/api-http.md | 62 ---- docs/zh/api-websocket.md | 67 ----- docs/zh/architecture.md | 197 ------------ docs/zh/backup.md | 82 ----- docs/zh/baraql.md | 597 ------------------------------------- docs/zh/btree.md | 26 -- docs/zh/changelog.md | 76 ----- docs/zh/clients.md | 66 ---- docs/zh/columnar.md | 50 ---- docs/zh/configuration.md | 217 -------------- docs/zh/crossmodal.md | 48 --- docs/zh/deployment.md | 249 ---------------- docs/zh/distributed.md | 91 ------ docs/zh/docker.md | 129 -------- docs/zh/fts.md | 47 --- docs/zh/graph.md | 42 --- docs/zh/index.md | 59 ---- docs/zh/installation.md | 309 ------------------- docs/zh/lsm.md | 48 --- docs/zh/mcp.md | 109 ------- docs/zh/monitoring.md | 104 ------- docs/zh/performance.md | 94 ------ docs/zh/protocol.md | 67 ----- docs/zh/quickstart.md | 134 --------- docs/zh/schema.md | 46 --- docs/zh/security.md | 188 ------------ docs/zh/storage.md | 78 ----- docs/zh/transactions.md | 77 ----- docs/zh/troubleshooting.md | 118 -------- docs/zh/udf.md | 47 --- docs/zh/vector.md | 65 ---- 196 files changed, 6 insertions(+), 20632 deletions(-) delete mode 100644 docs/ar/api-binary.md delete mode 100644 docs/ar/api-http.md delete mode 100644 docs/ar/api-websocket.md delete mode 100644 docs/ar/architecture.md delete mode 100644 docs/ar/backup.md delete mode 100644 docs/ar/baraql.md delete mode 100644 docs/ar/btree.md delete mode 100644 docs/ar/changelog.md delete mode 100644 docs/ar/clients.md delete mode 100644 docs/ar/columnar.md delete mode 100644 docs/ar/configuration.md delete mode 100644 docs/ar/crossmodal.md delete mode 100644 docs/ar/deployment.md delete mode 100644 docs/ar/distributed.md delete mode 100644 docs/ar/docker.md delete mode 100644 docs/ar/fts.md delete mode 100644 docs/ar/graph.md delete mode 100644 docs/ar/index.md delete mode 100644 docs/ar/installation.md delete mode 100644 docs/ar/lsm.md delete mode 100644 docs/ar/mcp.md delete mode 100644 docs/ar/monitoring.md delete mode 100644 docs/ar/performance.md delete mode 100644 docs/ar/protocol.md delete mode 100644 docs/ar/quickstart.md delete mode 100644 docs/ar/schema.md delete mode 100644 docs/ar/security.md delete mode 100644 docs/ar/storage.md delete mode 100644 docs/ar/transactions.md delete mode 100644 docs/ar/troubleshooting.md delete mode 100644 docs/ar/udf.md delete mode 100644 docs/ar/vector.md delete mode 100644 docs/de/api-binary.md delete mode 100644 docs/de/api-http.md delete mode 100644 docs/de/api-websocket.md delete mode 100644 docs/de/architecture.md delete mode 100644 docs/de/backup.md delete mode 100644 docs/de/baraql.md delete mode 100644 docs/de/btree.md delete mode 100644 docs/de/changelog.md delete mode 100644 docs/de/clients.md delete mode 100644 docs/de/columnar.md delete mode 100644 docs/de/configuration.md delete mode 100644 docs/de/crossmodal.md delete mode 100644 docs/de/deployment.md delete mode 100644 docs/de/distributed.md delete mode 100644 docs/de/docker.md delete mode 100644 docs/de/fts.md delete mode 100644 docs/de/graph.md delete mode 100644 docs/de/index.md delete mode 100644 docs/de/installation.md delete mode 100644 docs/de/lsm.md delete mode 100644 docs/de/mcp.md delete mode 100644 docs/de/monitoring.md delete mode 100644 docs/de/performance.md delete mode 100644 docs/de/protocol.md delete mode 100644 docs/de/quickstart.md delete mode 100644 docs/de/schema.md delete mode 100644 docs/de/security.md delete mode 100644 docs/de/storage.md delete mode 100644 docs/de/transactions.md delete mode 100644 docs/de/troubleshooting.md delete mode 100644 docs/de/udf.md delete mode 100644 docs/de/vector.md delete mode 100644 docs/fa/api-binary.md delete mode 100644 docs/fa/api-http.md delete mode 100644 docs/fa/api-websocket.md delete mode 100644 docs/fa/architecture.md delete mode 100644 docs/fa/backup.md delete mode 100644 docs/fa/baraql.md delete mode 100644 docs/fa/btree.md delete mode 100644 docs/fa/changelog.md delete mode 100644 docs/fa/clients.md delete mode 100644 docs/fa/columnar.md delete mode 100644 docs/fa/configuration.md delete mode 100644 docs/fa/crossmodal.md delete mode 100644 docs/fa/deployment.md delete mode 100644 docs/fa/distributed.md delete mode 100644 docs/fa/docker.md delete mode 100644 docs/fa/fts.md delete mode 100644 docs/fa/graph.md delete mode 100644 docs/fa/index.md delete mode 100644 docs/fa/installation.md delete mode 100644 docs/fa/lsm.md delete mode 100644 docs/fa/mcp.md delete mode 100644 docs/fa/monitoring.md delete mode 100644 docs/fa/performance.md delete mode 100644 docs/fa/protocol.md delete mode 100644 docs/fa/quickstart.md delete mode 100644 docs/fa/schema.md delete mode 100644 docs/fa/security.md delete mode 100644 docs/fa/storage.md delete mode 100644 docs/fa/transactions.md delete mode 100644 docs/fa/troubleshooting.md delete mode 100644 docs/fa/udf.md delete mode 100644 docs/fa/vector.md delete mode 100644 docs/ru/api-binary.md delete mode 100644 docs/ru/api-http.md delete mode 100644 docs/ru/api-websocket.md delete mode 100644 docs/ru/architecture.md delete mode 100644 docs/ru/backup.md delete mode 100644 docs/ru/baraql.md delete mode 100644 docs/ru/btree.md delete mode 100644 docs/ru/changelog.md delete mode 100644 docs/ru/clients.md delete mode 100644 docs/ru/columnar.md delete mode 100644 docs/ru/configuration.md delete mode 100644 docs/ru/crossmodal.md delete mode 100644 docs/ru/deployment.md delete mode 100644 docs/ru/distributed.md delete mode 100644 docs/ru/docker.md delete mode 100644 docs/ru/fts.md delete mode 100644 docs/ru/graph.md delete mode 100644 docs/ru/index.md delete mode 100644 docs/ru/installation.md delete mode 100644 docs/ru/lsm.md delete mode 100644 docs/ru/mcp.md delete mode 100644 docs/ru/monitoring.md delete mode 100644 docs/ru/performance.md delete mode 100644 docs/ru/protocol.md delete mode 100644 docs/ru/quickstart.md delete mode 100644 docs/ru/schema.md delete mode 100644 docs/ru/security.md delete mode 100644 docs/ru/storage.md delete mode 100644 docs/ru/transactions.md delete mode 100644 docs/ru/troubleshooting.md delete mode 100644 docs/ru/udf.md delete mode 100644 docs/ru/vector.md delete mode 100644 docs/tr/api-binary.md delete mode 100644 docs/tr/api-http.md delete mode 100644 docs/tr/api-websocket.md delete mode 100644 docs/tr/architecture.md delete mode 100644 docs/tr/backup.md delete mode 100644 docs/tr/baraql.md delete mode 100644 docs/tr/btree.md delete mode 100644 docs/tr/changelog.md delete mode 100644 docs/tr/clients.md delete mode 100644 docs/tr/columnar.md delete mode 100644 docs/tr/configuration.md delete mode 100644 docs/tr/crossmodal.md delete mode 100644 docs/tr/deployment.md delete mode 100644 docs/tr/distributed.md delete mode 100644 docs/tr/docker.md delete mode 100644 docs/tr/fts.md delete mode 100644 docs/tr/graph.md delete mode 100644 docs/tr/index.md delete mode 100644 docs/tr/installation.md delete mode 100644 docs/tr/lsm.md delete mode 100644 docs/tr/mcp.md delete mode 100644 docs/tr/monitoring.md delete mode 100644 docs/tr/performance.md delete mode 100644 docs/tr/protocol.md delete mode 100644 docs/tr/quickstart.md delete mode 100644 docs/tr/schema.md delete mode 100644 docs/tr/security.md delete mode 100644 docs/tr/storage.md delete mode 100644 docs/tr/transactions.md delete mode 100644 docs/tr/troubleshooting.md delete mode 100644 docs/tr/udf.md delete mode 100644 docs/tr/vector.md delete mode 100644 docs/zh/api-binary.md delete mode 100644 docs/zh/api-http.md delete mode 100644 docs/zh/api-websocket.md delete mode 100644 docs/zh/architecture.md delete mode 100644 docs/zh/backup.md delete mode 100644 docs/zh/baraql.md delete mode 100644 docs/zh/btree.md delete mode 100644 docs/zh/changelog.md delete mode 100644 docs/zh/clients.md delete mode 100644 docs/zh/columnar.md delete mode 100644 docs/zh/configuration.md delete mode 100644 docs/zh/crossmodal.md delete mode 100644 docs/zh/deployment.md delete mode 100644 docs/zh/distributed.md delete mode 100644 docs/zh/docker.md delete mode 100644 docs/zh/fts.md delete mode 100644 docs/zh/graph.md delete mode 100644 docs/zh/index.md delete mode 100644 docs/zh/installation.md delete mode 100644 docs/zh/lsm.md delete mode 100644 docs/zh/mcp.md delete mode 100644 docs/zh/monitoring.md delete mode 100644 docs/zh/performance.md delete mode 100644 docs/zh/protocol.md delete mode 100644 docs/zh/quickstart.md delete mode 100644 docs/zh/schema.md delete mode 100644 docs/zh/security.md delete mode 100644 docs/zh/storage.md delete mode 100644 docs/zh/transactions.md delete mode 100644 docs/zh/troubleshooting.md delete mode 100644 docs/zh/udf.md delete mode 100644 docs/zh/vector.md diff --git a/README.md b/README.md index 2179fc6..fa38f4f 100644 --- a/README.md +++ b/README.md @@ -5,12 +5,12 @@ **A multimodal database engine written in Nim — 100% native, zero dependencies.** [![Version](https://img.shields.io/badge/version-1.1.6-blue.svg)](baradadb.nimble) -[![Documentation](https://img.shields.io/badge/docs-7_languages-blue.svg)](docs/index.md) +[![Documentation](https://img.shields.io/badge/docs-2_languages-blue.svg)](docs/index.md) [![Stars](https://img.shields.io/github/stars/katehonz/barabaDB?style=social)](https://github.com/katehonz/barabaDB) ## Documentation -📖 **[Read the documentation in your language](docs/index.md)** — English, Български, Русский, فارسی, 中文, Türkçe, العربية +📖 **[Read the documentation in your language](docs/index.md)** — English, Български BaraDB combines document, graph, vector, columnar, and full-text search storage in a single engine with a unified query language (BaraQL). It compiles to a @@ -112,7 +112,7 @@ nimble bench ## BaraQL — Query Language -BaraQL is SQL-compatible with extensions for graph, vector, and document queries. +BaraQL implements partial SQL:2023 coverage with extensions for graph, vector, and document queries. ### Basic Queries diff --git a/docs/ar/api-binary.md b/docs/ar/api-binary.md deleted file mode 100644 index 1516416..0000000 --- a/docs/ar/api-binary.md +++ /dev/null @@ -1,62 +0,0 @@ -# API البروتوكول الثنائي - -بروتوكول سلكي منخفض المستوى لاتصالات العميل عالية الأداء. - -## تنسيق الرسالة - -جميع الرسائل تستخدم ترتيب big-endian: - -``` -┌────────┬────────┬────────┬────────┬─────────────┐ -│ Length │ Type │ Seq │ Status │ Payload │ -│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ -└────────┴────────┴────────┴────────┴─────────────┘ -``` - -## أنواع الرسائل - -### 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) -``` - -## رموز الاستجابة - -| الرمز | الاسم | الوصف | -|-------|-------|-------| -| 0x00 | OK | نجاح | -| 0x01 | ERROR | خطأ عام | -| 0x02 | AUTH_REQUIRED | مطلوب مصادقة | -| 0x03 | INVALID_QUERY | خطأ في بناء الجملة | -| 0x04 | NOT_FOUND | المورد غير موجود | \ No newline at end of file diff --git a/docs/ar/api-http.md b/docs/ar/api-http.md deleted file mode 100644 index 68f194d..0000000 --- a/docs/ar/api-http.md +++ /dev/null @@ -1,62 +0,0 @@ -# API HTTP/REST - -API REST مبني على JSON لتطبيقات الويب. - -## Base URL - -``` -http://localhost:9470/api -``` - -## نقاط النهاية - -### GET /api/users - -قائمة جميع المستخدمين: - -```bash -curl http://localhost:9470/api/users -``` - -### GET /api/users/:id - -الحصول على المستخدم بالـ ID: - -```bash -curl http://localhost:9470/api/users/1 -``` - -### POST /api/users - -إنشاء مستخدم: - -```bash -curl -X POST http://localhost:9470/api/users \ - -d '{"Name": "Charlie", "age": 35}' -``` - -### PUT /api/users/:id - -تحديث مستخدم: - -```bash -curl -X PUT http://localhost:9470/api/users/1 \ - -d '{"Name": "Alice", "age": 31}' -``` - -### DELETE /api/users/:id - -حذف مستخدم: - -```bash -curl -X DELETE http://localhost:9470/api/users/1 -``` - -## نقطة نهاية الاستعلام - -تنفيذ استعلامات BaraQL عبر HTTP: - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"sql": "SELECT * FROM users WHERE age > 18"}' -``` \ No newline at end of file diff --git a/docs/ar/api-websocket.md b/docs/ar/api-websocket.md deleted file mode 100644 index b4370ea..0000000 --- a/docs/ar/api-websocket.md +++ /dev/null @@ -1,78 +0,0 @@ -# API WebSocket - -دفق كامل للاتجاهين لتغذية البيانات في الوقت الفعلي والإشعارات. - -## الاتصال - -``` -ws://localhost:9471/ws -``` - -## مثال العميل - -```javascript -const ws = new WebSocket('ws://localhost:9471/ws'); - -ws.onopen = () => { - ws.send(JSON.stringify({ - type: 'query', - sql: 'SELECT * FROM users' - })); -}; - -ws.onmessage = (event) => { - console.log('Received:', JSON.parse(event.data)); -}; -``` - -## تنسيق الرسالة - -```json -{ - "type": "query", - "id": "uuid", - "sql": "SELECT * FROM users" -} -``` - -## أنواع الرسائل - -### طلب الاستعلام - -```json -{ - "type": "query", - "id": "123", - "sql": "SELECT * FROM users" -} -``` - -### استجابة الاستعلام - -```json -{ - "type": "result", - "id": "123", - "data": [{"id": 1, "name": "Alice"}] -} -``` - -### الاشتراك - -```json -{ - "type": "subscribe", - "table": "users" -} -``` - -### إشعار - -```json -{ - "type": "push", - "table": "users", - "action": "insert", - "data": {"id": 3, "name": "Charlie"} -} -``` \ No newline at end of file diff --git a/docs/ar/architecture.md b/docs/ar/architecture.md deleted file mode 100644 index 09022c3..0000000 --- a/docs/ar/architecture.md +++ /dev/null @@ -1,102 +0,0 @@ -# بنية BaraDB - -## نظرة عامة - -BaraDB هو **محرك قاعدة بيانات متعدد الأنماط** مكتوب بـ Nim يجمع بين تخزين المستندات (KV) والرسم البياني والمتجهي والعمودي والبحث النصي الكامل في محرك واحد مع لغة استعلام موحدة **BaraQL**. - -## البنية الطبقية - -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. طبقة العميل │ -│ البروتوكول الثنائي │ HTTP/REST │ WebSocket │ مضمن │ -├─────────────────────────────────────────────────────────┤ -│ 2. طبقة الاستعلام (BaraQL) │ -│ المحلل اللغوي → المحلل → AST → IR → المحسن → توليد الكود│ -├─────────────────────────────────────────────────────────┤ -│ 3. محركات التنفيذ │ -│ المستندات │ الرسم البياني │ المتجه │ العمودي │ FTS │ -├─────────────────────────────────────────────────────────┤ -│ 4. التخزين │ -│ LSM-Tree │ B-Tree │ WAL │ Bloom │ الضغط │ الذاكرة المؤقتة│ -├─────────────────────────────────────────────────────────┤ -│ 5. الموزع │ -│ توافق Raft │ التجزئة │ النسخ │ Gossip │ -└─────────────────────────────────────────────────────────┘ -``` - -## الطبقة 1: طبقة العميل - -- **البروتوكول الثنائي**: بروتوكول ثنائي فعال big-endian -- **HTTP/REST**: واجهة REST مبنية على JSON -- **WebSocket**: دفق ثنائي الاتجاه كامل -- **المدمج**: وصول مباشر داخل العملية - -## الطبقة 2: طبقة الاستعلام (BaraQL) - -1. **المحلل اللغوي** (`query/lexer.nim`): أكثر من 80 نوع رمز -2. **المحلل** (`query/parser.nim`): محلل تنازلي تكراري -3. **AST** (`query/ast.nim`): أكثر من 25 نوع عقدة -4. **IR** (`query/ir.nim`): تمثيل وسيط -5. **المحسن** (`query/adaptive.nim`): تحسين عبر الأنماط -6. **توليد الكود** (`query/codegen.nim`): ترجمة إلى عمليات التخزين -7. **المنفذ** (`query/executor.nim`): تنفيذ متوازي - -## الطبقة 3: محركات التنفيذ - -### محرك المستندات/KV -- **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTables - -### المحرك المتجهي (`vector/`) -- **فهرس HNSW** (`vector/engine.nim`): رسم بياني صغير قابل للملاحة هرمي -- **فهرس IVF-PQ**: ملف مقلوب مع تكميم المنتج -- **عمليات SIMD** (`vector/simd.nim`): محسّن بـ AVX2 - -### محرك الرسم البياني (`graph/`) -- BFS، DFS، Dijkstra، PageRank -- **Louvain**: كشف المجتمع - -### البحث النصي الكامل (`fts/`) -- الفهرس المقلوب، BM25، TF-IDF -- **متعدد اللغات**: tokenizers لـ EN، BG، DE، FR، RU - -## الطبقة 4: التخزين - -- **LSM-Tree**: MemTable، WAL، SSTable، Bloom Filter -- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU -- **I/O المعينة**: وصول قائم على mmap -- **الاستعادة**: إعادة تشغيل WAL - -## الطبقة 5: الموزع - -- **توافق Raft** (`core/raft.nim`): انتخاب القائد، نسخ السجل -- **التجزئة** (`core/sharding.nim`): hash، range، تجزئة متسقة -- **النسخ** (`core/replication.nim`): متزامن، غير متزامن، شبه متزامن -- **بروتوكول Gossip** (`core/gossip.nim`): مثل SWIM - -## قرارات التصميم الرئيسية - -1. **Nim نقي**: بدون تبعيات Cython أو Python أو Rust -2. **تخزين موحد**: محرك واحد لـ KV والرسم البياني والمتجة وFTS والعمودي -3. **الوضع المدمج**: يمكن تشغيله كمكتبة أو خادم -4. **البروتوكول الثنائي**: بروتوكول سلكي فعال مخصص -5. **MVCC**: تحكم في التزامن متعدد الإصدارات -6. **المخطط أولاً**: نظام مخطط مكتوب بشدة مع الوراثة -7. **عبر الأنماط**: لغة استعلام واحدة عبر جميع نماذج البيانات -8. **التحقق الرسمي**: الخوارزميات الموزعة الأساسية محددة في TLA+ ومتحقق منها مع TLC - -## إحصائيات الوحدات - -| الفئة | الوحدات | أسطر الكود | الغرض | -|-------|---------|------------|-------| -| Core | 16 | ~4,200 | الخادم، البروتوكولات، المعاملات، الموزع | -| Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، الضغط، mmap | -| Query | 7 | ~2,800 | المحلل اللغوي، المحلل، AST، IR، المحسن، توليد الكود | -| Vector | 3 | ~1,200 | HNSW، IVF-PQ، التكميم، SIMD | -| Graph | 3 | ~1,000 | قائمة الجوار، الخوارزميات، كشف المجتمع | -| FTS | 2 | ~900 | الفهرس المقلوب، BM25، غامض، متعدد اللغات | -| Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، pool، auth، حد السعر، SSL | -| Schema | 1 | ~600 | الأنواع، الروابط، الوراثة | -| Client | 2 | ~800 | عميل Nim الثنائي | -| CLI | 1 | ~400 | صدفة BaraQL التفاعلية | -| **المجموع** | **49** | **~14,100** | | \ No newline at end of file diff --git a/docs/ar/backup.md b/docs/ar/backup.md deleted file mode 100644 index b34aac9..0000000 --- a/docs/ar/backup.md +++ /dev/null @@ -1,82 +0,0 @@ -# النسخ الاحتياطي والاستعادة - -## لقطات عبر الإنترنت - -تدعم BaraDB اللقطات عبر الإنترنت دون إيقاف الخادم. - -### إنشاء لقطة - -```nim -import barabadb/core/backup - -var bm = newBackupManager() -bm.createSnapshot("/backup/baradb_2025-01-15") -``` - -### عبر CLI - -```bash -./build/baradadb --snapshot --output=/backup/snapshot.db -``` - -### عبر HTTP API - -```bash -curl -X POST http://localhost:9470/api/backup \ - -d '{"destination": "/backup/snapshot.db"}' -``` - -### النسخ الاحتياطي التلقائي - -```bash -0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db -find /backup -name "baradb_*.db" -mtime +7 -delete -``` - -## استعادة نقطة في الوقت (PITR) - -### الاستعادة من اللقطة + WAL - -```bash -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal -``` - -### الاستعادة عبر SQL - -```sql -RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; -``` - -## سيناريوهات استعادة الكوارث - -### السيناريو 1: تلف الملف - -```bash -cp /backup/sstables/000012.sst ./data/sstables/ -./build/baradadb --rebuild-index -``` - -### السيناريو 2: فقدان البيانات الكامل - -```bash -cp /backup/snapshot.db ./data/ -./build/baradadb --recover --wal-dir=/backup/wal -``` - -### السيناريو 3: فشل عقدة الكتلة - -```bash -BARADB_RAFT_NODE_ID=newnode \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## أفضل الممارسات - -1. اختبار الاستعادة بانتظام -2. تخزين النسخ الاحتياطية خارج الموقع -3. تشفير النسخ الاحتياطية -4. مراقبة مهام النسخ الاحتياطي -5. توثيق RTO/RPO \ No newline at end of file diff --git a/docs/ar/baraql.md b/docs/ar/baraql.md deleted file mode 100644 index 8c10a06..0000000 --- a/docs/ar/baraql.md +++ /dev/null @@ -1,268 +0,0 @@ -# مرجع لغة استعلام BaraQL - -BaraQL هي لغة استعلام متوافقة مع SQL مع امتدادات لعمليات الرسم البياني والمتجة والمستندات. - -## أنواع البيانات - -| النوع | الوصف | مثال | -|-------|-------|------| -| `null` | قيمة فارغة | `null` | -| `bool` | منطقي | `true`, `false` | -| `int8` | عدد صحيح 8 بت | `127` | -| `int16` | عدد صحيح 16 بت | `32767` | -| `int32` | عدد صحيح 32 بت | `2147483647` | -| `int64` | عدد صحيح 64 بت | `9223372036854775807` | -| `float32` | فاصلة عائمة 32 بت | `3.14` | -| `float64` | فاصلة عائمة 64 بت | `3.14159265359` | -| `str` | سلسلة UTF-8 | `'hello'` | -| `vector` | متجه float32 | `[0.1, 0.2, 0.3]` | -| `datetime` | طابع زمني ISO 8601 | `'2025-01-15T10:30:00Z'` | -| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` | - -## الاستعلامات الأساسية - -### SELECT - -```sql -SELECT * FROM users; -SELECT name, age FROM users; -SELECT name AS full_name FROM users; -SELECT * FROM users LIMIT 10 OFFSET 20; -``` - -### WHERE - -```sql -SELECT * FROM users WHERE age > 18; -SELECT * FROM users WHERE age BETWEEN 18 AND 65; -SELECT * FROM users WHERE department IN ('Engineering', 'Sales'); -SELECT * FROM users WHERE name LIKE 'A%'; -``` - -### INSERT - -```sql -INSERT users { name := 'Alice', age := 30 }; -``` - -### UPDATE - -```sql -UPDATE users SET age = 31 WHERE name = 'Alice'; -``` - -### DELETE - -```sql -DELETE FROM users WHERE name = 'Bob'; -``` - -## JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -## CTE (تعبيرات الجدول المشترك) - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## البحث المتجهي - -```sql -INSERT articles { title := 'Nim Programming', embedding := [0.1, 0.2, 0.3, 0.4] }; - -SELECT title FROM articles -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; -``` - -## أنماط الرسم البياني - -```sql -MATCH (p:Person)-[:KNOWS]->(friend:Person) -WHERE p.name = 'Alice' -RETURN friend.name; -``` - -## المعاملات - -```sql -BEGIN; -INSERT users { name := 'Alice', age := 30 }; -INSERT orders { user_id := last_insert_id(), total := 100 }; -COMMIT; - --- مع نقطة حفظ -BEGIN; -INSERT users { name := 'Bob', age := 25 }; -SAVEPOINT sp1; -INSERT orders { user_id := last_insert_id(), total := 200 }; --- خطأ، التراجع إلى نقطة الحفظ -ROLLBACK TO sp1; -COMMIT; -``` - -## البحث النصي الكامل - -```sql --- بحث أساسي -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('database programming'); - --- مع درجة الصلة -SELECT title, relevance() -FROM articles -WHERE MATCH(title, body) AGAINST('Nim language') -ORDER BY relevance() DESC; - --- الوضع المنطقي -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE); - --- البحث الضبابي -SELECT * FROM articles -WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2); -``` - -## الدوال المحددة من المستخدم - -```sql --- تسجيل UDF -CREATE FUNCTION greet(name str) -> str { - RETURN 'Hello, ' || name || '!'; -}; - --- استخدامها -SELECT greet(name) FROM users; - --- الدوال المدمجة -SELECT abs(-5), sqrt(16), lower('HELLO'), len('test'); -``` - -## تلميحات الاستعلام - -```sql --- فرض استخدام الفهرس -SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18; - --- فرض البحث المتجهي التقريبي -SELECT /*+ APPROXIMATE */ * FROM vectors -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; - --- التنفيذ المتوازي -SELECT /*+ PARALLEL(4) */ * FROM large_table; -``` - -## دوال النوافذ - -```sql --- دوال الترتيب -SELECT - name, - department, - ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn, - RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r, - DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr -FROM employees; - --- دوال القيمة -SELECT - name, - salary, - LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary, - LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary, - FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest, - LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive -FROM employees; - --- دوال التوزيع -SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees; -``` - -### مواصفات الإطار - -```sql --- إطار ROWS -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - ROWS BETWEEN 1 PRECEDING AND CURRENT ROW -) - --- إطار RANGE -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW -) -``` - -## ERP متعدد المستأجرين - -يدعم BaraDB تشغيل عدة شركات (مستأجرين) في مثيل قاعدة بيانات واحد، باستخدام **أمان مستوى الصف (RLS)** مع **متغيرات الجلسة**. - -### متغيرات الجلسة - -```sql -SET app.tenant_id = 'company-123'; -SELECT current_setting('app.tenant_id') AS tenant; -``` - -### المستخدم / الدور الحالي - -```sql -SELECT current_user AS me, current_role AS my_role; -``` - -### عزل المستأجر عبر RLS - -```sql --- تمكين RLS على جدول -ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; - --- إنشاء سياسة تصفية حسب المستأجر -CREATE POLICY tenant_isolation ON invoices - FOR SELECT USING (tenant_id = current_setting('app.tenant_id')); - --- كل جلسة ترى فقط بياناتها -SET app.tenant_id = 'company-a'; -SELECT * FROM invoices; -- صفوف company-a فقط -``` - -### لماذا متعدد المستأجرين؟ - -- **مثيل واحد، مستأجرون كثيرون** — لا حاجة لتشغيل 100 قاعدة بيانات منفصلة -- **مستندات JSONB** — تخزين مخطط مرن، سهل إضافة حقول لكل مستأجر -- **RLS يضمن العزل** — قاعدة البيانات تفرض حدود المستأجر، وليس فقط التطبيق - -## الكلمات المفتاحية المدعومة - -| الفئة | الكلمات المفتاحية | -|----------|----------| -| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT | -| DML | INSERT, UPDATE, DELETE, SET, VALUES | -| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE | -| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON | -| Set | UNION, UNION ALL, INTERSECT, EXCEPT | -| CTEs | WITH, RECURSIVE, AS | -| Case | CASE, WHEN, THEN, ELSE, END | -| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT | -| Graph | MATCH, RETURN, WHERE, shortestPath, type | -| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS | -| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> | -| JSON | ->, ->> | -| FTS | @@ (تطابق BM25) | -| Recovery | RECOVER TO TIMESTAMP | -| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting | -| Session | SET, current_setting, current_user, current_role | -| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING | -| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE | \ No newline at end of file diff --git a/docs/ar/btree.md b/docs/ar/btree.md deleted file mode 100644 index 48152ae..0000000 --- a/docs/ar/btree.md +++ /dev/null @@ -1,26 +0,0 @@ -# فهرس B-Tree - -هيكل فهرس مرتب للبحث النطاقي والنقطة الفعال. - -## الاستخدام - -```nim -import barabadb/storage/btree - -var btree = newBTreeIndex[string, string]() - -btree.insert("key1", "value1") -btree.insert("key2", "value2") - -let values = btree.get("key1") -let range = btree.scan("key_a", "key_z") -btree.delete("key1") -``` - -## الميزات - -- تخزين مفاتي-قيم مرتب -- استعلامات النطاق (BETWEEN, >, <, >=, <=) -- المسح بالبادئة -- حجم الصفحة القابل للتكوين -- دعم المكرر \ No newline at end of file diff --git a/docs/ar/changelog.md b/docs/ar/changelog.md deleted file mode 100644 index 7abea55..0000000 --- a/docs/ar/changelog.md +++ /dev/null @@ -1,76 +0,0 @@ -# سجل التغييرات - -## [0.1.0] — 2025-01-15 - -### المضاف - -- **محركات التخزين الأساسية** - - LSM-Tree مع MemTable و WAL و SSTables و size-tiered compaction - - فهرس B-Tree مرتب مع المسح النطاقي و MVCC copy-on-write - - فلاتر Bloom - - I/O المعينة بالذاكرة - - ذاكرة صفحة LRU - -- **محرك الاستعلام (BaraQL)** - - lexer متوافق مع SQL مع 80+ نوع رمز - - parser تنازلي تكراري ينتج AST مع 25+ نوع عقدة - - تمثيل وسيط (IR) - - محسن استعلام تكيفي مع تخطيط عبر الأنماط - - منفذ استعلام مع 병렬화 - -- **ميزات لغة BaraQL** - - SELECT و INSERT و UPDATE و DELETE - - WHERE و ORDER BY و LIMIT و OFFSET - - GROUP BY و HAVING ودوال التجميع - - INNER JOIN و LEFT JOIN و RIGHT JOIN و FULL JOIN و CROSS JOIN - - CTEs مع WITH - - الاستعلامات الفرعية - - تعبيرات CASE - - UNION و INTERSECT و EXCEPT - -- **محرك المتجهات** - - فهرس HNSW - - فهرس IVF-PQ - - دوال المسافة المحسنة بـ SIMD - - التكميم: 8-bit/4-bit القياسي والمنتج والثنائي - -- **محرك الرسم البياني** - - تخزين قائمة المجاورة - - BFS و DFS للعبور - - Dijkstra لأقصر مسار - - PageRank - - Louvain لكشف المجتمع - - محلل استعلامات Cypher - -- **البحث النصي الكامل** - - الفهرس المقلوب - - ترتيب BM25 - - TF-IDF - - البحث الغامض - - tokenizers متعدد اللغات - -- **البروتوكولات** - - بروتوكول Wire الثنائي مع 16 نوع رسالة - - API HTTP/REST JSON - - WebSocket للدفق - - تجميع الاتصالات - - مصادقة JWT - - TLS/SSL - -- **الأنظمة الموزعة** - - توافق Raft - - تجزئة hash و range و consistent-hash - - نسخ متزامن/غير متزامن/شبه متزامن - - بروتوكول Gossip - - commit على مرحلتين - -### الأداء - -- LSM-Tree: 580K كتابة/ثانية، 720K قراءة/ثانية -- B-Tree: 1.2M إدراج/ثانية، 1.5M بحث/ثانية -- Vector SIMD: 850K مسافة جيب التمام/ثانية (dim=768) - -### الاختبارات - -- 262 اختبار عبر 56 مجموعة اختبار -- 100% معدل النجاح \ No newline at end of file diff --git a/docs/ar/clients.md b/docs/ar/clients.md deleted file mode 100644 index a7ac77f..0000000 --- a/docs/ar/clients.md +++ /dev/null @@ -1,66 +0,0 @@ -# حزم العملاء - -توفر BaraDB مكتبات العملاء الرسمية لـ JavaScript/TypeScript و Python و Nim و Rust. - -## JavaScript / TypeScript - -### التثبيت - -```bash -npm install baradb -``` - -### الاستخدام الأساسي - -```typescript -import { Client } from 'baradb'; - -const client = new Client('localhost', 9472); -await client.connect(); - -const result = await client.query('SELECT name, age FROM users WHERE age > 18'); -``` - -## Python - -### التثبيت - -```bash -pip install baradb -``` - -### الاستخدام الأساسي - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -result = client.query("SELECT name, age FROM users WHERE age > 18") -``` - -## Nim (الوضع المدمج) - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## Rust - -```rust -use baradb::Client; - -let mut client = Client::connect("localhost:9472").await?; -``` - -## HTTP/REST - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` \ No newline at end of file diff --git a/docs/ar/columnar.md b/docs/ar/columnar.md deleted file mode 100644 index 246c5e9..0000000 --- a/docs/ar/columnar.md +++ /dev/null @@ -1,50 +0,0 @@ -# التخزين العمودي - -تخزين موجهة للأعمدة للاستعلامات التحليلية والتجميعات. - -## الاستخدام - -```nim -import barabadb/core/columnar - -var batch = newColumnBatch() -var ageCol = batch.addInt64Col("age") -var nameCol = batch.addStringCol("name") - -ageCol.appendInt64(25) -nameCol.appendString("Alice") -``` - -## التجميعات - -```nim -echo ageCol.sumInt64() -echo ageCol.avgInt64() -echo ageCol.minInt64() -echo ageCol.maxInt64() -``` - -## الترميز - -### RLE - -```nim -let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) -``` - -### Dictionary - -```nim -let dict = dictEncode(@["apple", "banana", "apple"]) -``` - -## أنواع الأعمدة - -| النوع | الوصف | -|-------|-------| -| `int32` | عدد صحيح 32 بت | -| `int64` | عدد صحيح 64 بت | -| `float32` | فاصلة عائمة 32 بت | -| `float64` | فاصلة عائمة 64 بت | -| `string` | سلسلة متغيرة الطول | -| `bool` | منطقي | \ No newline at end of file diff --git a/docs/ar/configuration.md b/docs/ar/configuration.md deleted file mode 100644 index c824355..0000000 --- a/docs/ar/configuration.md +++ /dev/null @@ -1,96 +0,0 @@ -# مرجع التكوين - -يمكن تكوين BaraDB عبر **متغيرات البيئة** أو **ملف التكوين** أو **علامات سطر الأوامر**. - -## ترتيب الأولوية - -1. علامات سطر الأوامر (الأعلى) -2. متغيرات البيئة -3. ملف التكوين (`baradb.conf` أو `baradb.json`) -4. الإعدادات الافتراضية (الأدنى) - -## متغيرات البيئة - -### الشبكة - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_ADDRESS` | `127.0.0.1` | عنوان الربط | -| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي | -| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP/REST API | -| `BARADB_WS_PORT` | `9471` | منفذ WebSocket | - -### التخزين - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_DATA_DIR` | `./data` | مسار دليل البيانات | -| `BARADB_MEMTABLE_SIZE_MB` | `64` | حجم MemTable (MB) | -| `BARADB_CACHE_SIZE_MB` | `256` | حجم ذاكرة الصفحة (MB) | - -### TLS/SSL - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_TLS_ENABLED` | `false` | تمكين TLS | -| `BARADB_CERT_FILE` | — | مسار شهادة TLS | -| `BARADB_KEY_FILE` | — | مسار مفتاح TLS الخاص | - -### الأمان - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_AUTH_ENABLED` | `false` | تمكين المصادقة | -| `BARADB_JWT_SECRET` | — | سر توقيع JWT | -| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | طلبات/ثانية عامة | -| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | طلبات/ثانية لكل عميل | - -## ملف التكوين - -### baradb.conf - -```ini -[server] -address = "0.0.0.0" -port = 9472 -http_port = 9470 - -[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" - -[auth] -enabled = true -jwt_secret = "change-me-in-production" -``` - -## علامات سطر الأوامر - -```bash -./build/baradadb --help -``` - -## أمثلة التكوين - -### التطوير - -```bash -./build/baradadb --log-level debug --data-dir ./dev_data -``` - -### الإنتاج - عقدة واحدة - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -BARADB_MEMTABLE_SIZE_MB=256 \ -BARADB_CACHE_SIZE_MB=1024 \ -./build/baradadb -``` \ No newline at end of file diff --git a/docs/ar/crossmodal.md b/docs/ar/crossmodal.md deleted file mode 100644 index 8f35cec..0000000 --- a/docs/ar/crossmodal.md +++ /dev/null @@ -1,48 +0,0 @@ -# الاستعلامات عبر الأنماط - -القدرة الفريدة لـ BaraDB هي تنفيذ استعلامات تمتد عبر محركات تخزين متعددة في بيان BaraQL موحد واحد. - -## نظرة عامة - -- **مستند/KV** (LSM-Tree) — السجلات المهيكلة -- **رسم بياني** (قائمة المجاورة) — العلاقات -- **متجهي** (HNSW/IVF-PQ) — بحث التشابه -- **نص كامل** (الفهرس المقلوب) — البحث النصي -- **عمودي** — التجميعات التحليلية - -## أنماط الاستعلام - -### متجه + نص كامل - -```sql -SELECT title FROM articles -WHERE MATCH(body) AGAINST('machine learning') -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; -``` - -### رسم بياني + متجه - -```sql -MATCH (u:User)-[:KNOWS]->(friend:User) -WHERE u.name = 'Alice' -ORDER BY cosine_distance(friend.taste_vector, u.taste_vector) -RETURN friend.name; -``` - -## التحسين - -### مخطط استعلام عبر الأنماط - -1. العامل الأكثر انتقائية أولاً -2. دفع المسندات إلى كل محرك -3. استخدام فلاتر Bloom لعمليات KV -4. 병렬화 الفروع المستقلة - -## الأداء - -| نوع الاستعلام | التأخير (10K صف) | -|---------------|------------------| -| FTS + Vector | 15 ms | -| Graph + Vector | 25 ms | -| FTS + Aggregate | 12 ms | \ No newline at end of file diff --git a/docs/ar/deployment.md b/docs/ar/deployment.md deleted file mode 100644 index 6f4d181..0000000 --- a/docs/ar/deployment.md +++ /dev/null @@ -1,68 +0,0 @@ -# دليل النشر - -## Docker - -### البداية السريعة - -```bash -docker build -t baradb:latest . -docker compose up -d -docker compose ps -``` - -### ملفات Docker Compose - -| الملف | الغرض | -|-------|-------| -| `docker-compose.yml` | التطوير | -| `docker-compose.prod.yml` | الإنتاج | - -## المنافذ - -| المنفذ | الوصف | -|--------|-------| -| `9472` | بروتوكول Wire الثنائي | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## متغيرات البيئة - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع | -| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي | -| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP | -| `BARADB_DATA_DIR` | `/data` | دليل البيانات | - -## المجلدات - -| المسار | الوصف | -|--------|-------| -| `/data` | دليل البيانات الرئيسي | -| `/data/server/wal` | سجل write-ahead | -| `/data/server/sstables` | ملفات SSTable | - -## قائمة التحقق للإنتاج - -- [ ] إنشاء شهادات TLS في `./certs/` -- [ ] تعيين `BARADB_JWT_SECRET` قوي -- [ ] تكوين قواعد جدار الحماية -- [ ] تكوين النسخ الاحتياطي المنتظم -- [ ] التحقق من حدود الموارد -- [ ] تكوين المراقبة - -## TLS في Docker - -```bash -mkdir -p certs -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout certs/server.key -out certs/server.crt -``` - -## النسخ الاحتياطي في Docker - -```bash -docker exec baradb /app/backup backup --data-dir=/data -docker exec baradb /app/backup list -docker exec baradb /app/backup restore --input=backup_xxx.tar.gz -``` \ No newline at end of file diff --git a/docs/ar/distributed.md b/docs/ar/distributed.md deleted file mode 100644 index fa845d5..0000000 --- a/docs/ar/distributed.md +++ /dev/null @@ -1,73 +0,0 @@ -# الأنظمة الموزعة - -تدعم BaraDB النشر الموزع مع توافق Raft والتجزئة والنسخ. - -## توافق Raft - -انتخاب القائد ونسخ السجل: - -```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() -``` - -## التجزئة - -```nim -import barabadb/core/sharding - -var router = newShardRouter(ShardConfig( - numShards: 4, - replicas: 2, - strategy: ssHash -)) -``` - -### استراتيجيات التجزئة - -| الاستراتيجية | الوصف | -|-------------|-------| -| `ssHash` | تجزئة قائمة على hash | -| `ssRange` | تجزئة قائمة على النطاق | -| `ssConsistent` | تجزئة متسقة | - -## النسخ - -```nim -import barabadb/core/replication - -var rm = newReplicationManager(rmSync) -rm.addReplica(newReplica("r1", "10.0.0.1", 9472)) -``` - -### أوضاع النسخ - -| الوضع | الوصف | -|-------|-------| -| `rmSync` | نسخ متزامن | -| `rmAsync` | نسخ غير متزامن | -| `rmSemiSync` | نسخ شبه متزامن | - -## المعاملات الموزعة - -الالتزام على مرحلتين: - -```nim -import barabadb/core/disttxn - -var dt = newDistributedTxn() -dt.prepare(@["node1", "node2"]) -dt.commit() -``` - -## التحقق الرسمي - -تم تحديد الخوارزميات الموزعة الأساسية في TLA+ والتحقق منها. \ No newline at end of file diff --git a/docs/ar/docker.md b/docs/ar/docker.md deleted file mode 100644 index 124c68d..0000000 --- a/docs/ar/docker.md +++ /dev/null @@ -1,78 +0,0 @@ -# دليل نشر Docker - -## البداية السريعة - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB - -docker build -t baradb:latest . - -docker compose up -d - -docker compose ps -docker compose logs -f -``` - -## الملفات - -| الملف | الوصف | -|-------|-------| -| `Dockerfile` | بناء multi-stage للإنتاج | -| `docker-compose.yml` | تكوين التطوير | -| `docker-compose.prod.yml` | تكوين الإنتاج | - -## بناء الصورة - -```bash -docker build -t baradb:latest . -``` - -## التشغيل - -### التطوير - -```bash -docker compose up -d -docker compose down -``` - -### الإنتاج - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -## المنافذ - -| المنفذ | الوصف | -|--------|-------| -| `9472` | بروتوكول Wire الثنائي | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## متغيرات البيئة - -| المتغير | الافتراضي | الوصف | -|---------|-----------|-------| -| `BARADB_ADDRESS` | `0.0.0.0` | عنوان الاستماع | -| `BARADB_PORT` | `9472` | منفذ البروتوكول الثنائي | -| `BARADB_HTTP_PORT` | `9470` | منفذ HTTP | -| `BARADB_DATA_DIR` | `/data` | دليل البيانات | - -## المجلدات - -| المسار | الوصف | -|--------|-------| -| `/data` | دليل البيانات الرئيسي | -| `/data/server/wal` | سجل write-ahead | -| `/data/server/sstables` | ملفات SSTable | - -## قائمة التحقق للإنتاج - -- [ ] إنشاء شهادات TLS في `./certs/` -- [ ] تعيين `BARADB_JWT_SECRET` قوي -- [ ] تكوين قواعد جدار الحماية -- [ ] تكوين النسخ الاحتياطي المنتظم -- [ ] التحقق من حدود الموارد -- [ ] تكوين المراقبة \ No newline at end of file diff --git a/docs/ar/fts.md b/docs/ar/fts.md deleted file mode 100644 index c55d9c0..0000000 --- a/docs/ar/fts.md +++ /dev/null @@ -1,47 +0,0 @@ -# محرك البحث النصي الكامل - -فهرس مقلوب مع ترتيب BM25 و TF-IDF للبحث النصي. - -## الاستخدام - -```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") - -let results = idx.search("programming language") -let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) -``` - -## طرق الترتيب - -### BM25 - -```nim -let bm25 = idx.searchBM25("query terms") -``` - -### TF-IDF - -```nim -let tfidf = idx.searchTfidf("query terms") -``` - -## ميزات البحث - -| الميزة | الوصف | -|---------|-------| -| Fuzzy search | تساهل مسافة Levenshtein | -| Wildcard | بادئة، لاحقة،wildcard中间 | -| Regex | أنماط التعبير العادي | -| Phrase search | تطابق عبارة تامة | -| Boolean | عوامل AND, OR, NOT | - -## واجهة SQL - -```sql -CREATE INDEX idx_fts ON articles(body) USING FTS; -SELECT * FROM articles WHERE body @@ 'machine learning'; -``` \ No newline at end of file diff --git a/docs/ar/graph.md b/docs/ar/graph.md deleted file mode 100644 index 75afed5..0000000 --- a/docs/ar/graph.md +++ /dev/null @@ -1,42 +0,0 @@ -# محرك الرسم البياني - -تخزين قائمة المجاورة مع خوارزميات مدمجة للعبور والتحليل. - -## الاستخدام - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -``` - -## الخوارزميات - -| الخوارزمية | الوصف | -|------------|-------| -| `bfs` | عبور بالعرض | -| `dfs` | عبور بالعمق | -| `dijkstra` | أقصر مسار موزون | -| `pageRank` | ترتيب أهمية العقدة | -| `louvain` | كشف المجتمع | -| `patternMatch` | تماثل الرسم الفرعي | - -## استعلام Cypher - -```nim -import barabadb/graph/cypher - -var engine = newCypherEngine(g) -let results = engine.execute(""" - MATCH (p:Person)-[:KNOWS]->(friend:Person) - WHERE p.name = 'Alice' - RETURN friend.name -""") -``` \ No newline at end of file diff --git a/docs/ar/index.md b/docs/ar/index.md deleted file mode 100644 index eaa2cc8..0000000 --- a/docs/ar/index.md +++ /dev/null @@ -1,59 +0,0 @@ -# توثيق BaraDB (العربية) - -**محرك قاعدة بيانات متعدد الأنماط مكتوب بـ Nim — 100% أصلي، بدون تبعيات.** - -## روابط سريعة - -> **ملاحظة:** التوثيق العربي قيد التطوير. يرجى الرجوع إلى [النسخة الإنجليزية](../en/) للمعلومات الكاملة. - -### البدء -- [التثبيت](../en/installation.md) -- [البداية السريعة](../en/quickstart.md) -- [نظرة عامة على البنية](../en/architecture.md) -- [مرجع التكوين](../en/configuration.md) -- [دليل النشر](../en/deployment.md) - -### المفاهيم الأساسية -- [لغة استعلام BaraQL](../en/baraql.md) -- [محركات التخزين](../en/storage.md) -- [نظام المخطط](../en/schema.md) -- [الاستعلامات عبر الأنماط](../en/crossmodal.md) - -### المحركات -- [تخزين LSM-Tree](../en/lsm.md) -- [فهرس B-Tree](../en/btree.md) -- [البحث المتجهي](../en/vector.md) -- [محرك الرسم البياني](../en/graph.md) -- [البحث النصي الكامل](../en/fts.md) -- [التخزين العمودي](../en/columnar.md) - -### API والعملاء -- [SDK للعملاء](../en/clients.md) -- [البروتوكول الثنائي](../en/api-binary.md) -- [HTTP/REST API](../en/api-http.md) -- [WebSocket API](../en/api-websocket.md) -- [مرجع البروتوكول](../en/protocol.md) - -### العمليات -- [الأداء والمعايير](../en/performance.md) -- [دليل الأمان](../en/security.md) -- [المراقبة](../en/monitoring.md) -- [النسخ الاحتياطي والاستعادة](../en/backup.md) -- [حل المشكلات](../en/troubleshooting.md) - -### متقدم -- [المعاملات و MVCC](../en/transactions.md) -- [الأنظمة الموزعة](../en/distributed.md) -- [الدوال المحددة من المستخدم](../en/udf.md) - ---- - -## معلومات المشروع - -- [سجل التغييرات](../en/changelog.md) -- [الترخيص](../../LICENSE) -- [مستودع GitHub](https://github.com/katehonz/barabaDB) - ---- - -*التوثيق العربي قيد الترجمة.* \ No newline at end of file diff --git a/docs/ar/installation.md b/docs/ar/installation.md deleted file mode 100644 index 7b6a842..0000000 --- a/docs/ar/installation.md +++ /dev/null @@ -1,308 +0,0 @@ -# دليل تثبيت BaraDB - -## المتطلبات - -- **مترجم Nim** >= 2.2.0 -- **ملفات رأس OpenSSL** (لدعم TLS) -- **نظام التشغيل**: لينكس، macOS، ويندوز - -### المنصات المدعومة - -| نظام التشغيل | البنية | الحالة | -|-------------|--------|--------| -| لينكس | x86_64 | ✅ دعم كامل | -| لينكس | ARM64 | ✅ دعم كامل | -| macOS | x86_64 | ✅ دعم كامل | -| macOS | ARM64 | ✅ دعم كامل | -| ويندوز | x86_64 | ✅ مدعوم | -| FreeBSD | x86_64 | 🟡 اختبار المجتمع | - -## تثبيت Nim - -### لينكس - -```bash -# المثبت الرسمي -curl https://nim-lang.org/choosenim/init.sh -sSf | sh - -# Ubuntu/Debian -sudo apt-get update -sudo apt-get install nim - -# Fedora -sudo dnf install nim - -# Arch Linux -sudo pacman -S nim -``` - -### macOS - -```bash -# Homebrew -brew install nim - -# MacPorts -sudo port install nim -``` - -### ويندوز - -```powershell -# باستخدام choosenim -curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell - - -# باستخدام winget -winget install nim - -# باستخدام scoop -scoop install nim -``` - -### التحقق من التثبيت - -```bash -nim --version -# المتوقع: Nim Compiler Version 2.2.0 أو أحدث -``` - -## تثبيت OpenSSL - -### لينكس - -```bash -# Ubuntu/Debian -sudo apt-get install libssl-dev - -# Fedora -sudo dnf install openssl-devel - -# Arch Linux -sudo pacman -S openssl -``` - -### macOS - -OpenSSL مضمن مع النظام. إذا لزم الأمر: - -```bash -brew install openssl -``` - -### ويندوز - -OpenSSL مضمن مع توزيع Nim ويندوز. للبناء اليدوي، قم بالتنزيل من [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html). - -## بناء BaraDB - -### استنساخ المستودع - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB -``` - -### تثبيت التبعيات - -```bash -nimble install -d -y -``` - -### خيارات البناء - -#### بناء التصحيح - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -#### بناء الإصدار (موصى به) - -```bash -nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim -``` - -#### استخدام مهام Nimble - -```bash -# بناء التصحيح -nimble build_debug - -# بناء الإصدار -nimble build_release -``` - -#### تقليل حجم الملف الثنائي - -```bash -nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim -strip build/baradadb -``` - -### التحقق من البناء - -```bash -./build/baradadb --version -# المتوقع: BaraDB v1.1.6 — Multimodal Database Engine -``` - -## تشغيل الاختبارات - -### جميع الاختبارات - -```bash -nim c -d:ssl -r tests/test_all.nim -``` - -### مجموعات اختبارات محددة - -```bash -# اختبارات التخزين -nim c -d:ssl -r tests/test_storage.nim - -# اختبارات محرك الاستعلام -nim c -d:ssl -r tests/test_query.nim - -# اختبارات البروتوكول -nim c -d:ssl -r tests/test_protocol.nim -``` - -### المعايير - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## خيارات التثبيت - -### التثبيت على مستوى النظام - -```bash -# بناء إصدار RELEASE -nimble build_release - -# التثبيت في /usr/local/bin -sudo cp build/baradadb /usr/local/bin/ -sudo chmod +x /usr/local/bin/baradadb - -# إنشاء دليل البيانات -sudo mkdir -p /var/lib/baradb -sudo chmod 755 /var/lib/baradb -``` - -### الملف الثنائي المبنى مسبقًا - -قم بتنزيل أحدث إصدار لمنصتك: - -```bash -# لينكس x86_64 -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 - -# لينكس ARM64 -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64 -chmod +x baradadb-linux-arm64 -mv baradadb-linux-arm64 /usr/local/bin/baradadb - -# macOS -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64 -chmod +x baradadb-darwin-amd64 -mv baradadb-darwin-amd64 /usr/local/bin/baradadb -``` - -### Docker - -```bash -# سحب الصورة الرسمية -docker pull barabadb/barabadb:latest - -# التشغيل -docker run -d \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - barabadb/barabadb -``` - -### Docker Compose - -```bash -docker-compose up -d -``` - -### الاستخدام المدمج (مشاريع Nim) - -أضف إلى ملف `.nimble` الخاص بك: - -```nim -requires "barabadb >= 1.1.6" -``` - -استخدم في الكود: - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## التشغيل الأول - -```bash -# بدء الخادم -./build/baradadb - -# المخرجات المتوقعة: -# BaraDB v1.1.6 — Multimodal Database Engine -# BaraDB TCP listening on 127.0.0.1:9472 - -# الاختبار عبر HTTP API -curl http://localhost:9470/health - -# الصدفة التفاعلية -./build/baradadb --shell -``` - -## حل مشكلات التثبيت - -### "cannot open file: hunos" - -```bash -nimble install -d -y -``` - -### "BaraDB requires SSL support" - -قم دائمًا بالبناء باستخدام `-d:ssl`: - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -### البناء البطيء - -استخدم البناء المتوازي: - -```bash -nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim -``` - -### حجم الملف الثنائي الكبير - -استخدم تحسين الحجم: - -```bash -nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim -``` - -## الخطوات التالية - -- [دليل البداية السريعة](quickstart.md) -- [مرجع التكوين](configuration.md) -- [نظرة عامة على البنية](architecture.md) -- [لغة استعلام BaraQL](baraql.md) \ No newline at end of file diff --git a/docs/ar/lsm.md b/docs/ar/lsm.md deleted file mode 100644 index 7a7ef5d..0000000 --- a/docs/ar/lsm.md +++ /dev/null @@ -1,48 +0,0 @@ -# محرك تخزين LSM-Tree - -محرك التخزين الأساسي في BaraDB باستخدام بنية Log-Structured Merge-Tree. - -## البنية - -``` -┌─────────────────────────────────────────────┐ -│ Writes │ -│ (append to WAL + MemTable) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ MemTable │ -│ (in-memory sorted buffer) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ SSTable │ -│ (sorted string table on disk) │ -└─────────────────────────────────────────────┘ -``` - -## الاستخدام - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") - -db.put("key1", cast[seq[byte]]("value1")) - -let (found, value) = db.get("key1") - -db.delete("key1") - -db.close() -``` - -## الميزات - -- **محسن للكتابة**: هيكل log-only إضافي -- **الدائمة**: WAL يضمن استعادة بعد الانهيار -- **Bloom Filter**: بحث سلبي سريع -- **الضغط**: استراتيجية size-tiered -- **ذاكرة الصفحة**: LRU للصفحاتaccessed بشكل متكرر \ No newline at end of file diff --git a/docs/ar/mcp.md b/docs/ar/mcp.md deleted file mode 100644 index d041d64..0000000 --- a/docs/ar/mcp.md +++ /dev/null @@ -1,109 +0,0 @@ -# خادم 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/ar/monitoring.md b/docs/ar/monitoring.md deleted file mode 100644 index 390a207..0000000 --- a/docs/ar/monitoring.md +++ /dev/null @@ -1,84 +0,0 @@ -# المراقبة والقابلية للملاحظة - -## فحوصات الصحة - -### نقطة نهاية صحة HTTP - -```bash -curl http://localhost:9470/health -``` - -الاستجابة: - -```json -{ - "status": "healthy", - "version": "0.1.0", - "uptime_seconds": 86400, - "checks": { - "storage": "ok", - "memory": "ok", - "connections": "ok" - } -} -``` - -## المقاييس - -### مقاييس متوافقة مع Prometheus - -```bash -curl http://localhost:9470/metrics -``` - -مثال على المخرجات: - -``` -baradb_queries_total 152340 -baradb_queries_duration_seconds_bucket{le="0.001"} 45000 -baradb_storage_lsm_size_bytes 2147483648 -baradb_cache_hit_rate 0.94 -baradb_active_connections 42 -``` - -## التسجيل - -### مستويات السجل - -| المستوى | الوصف | -|---------|-------| -| `debug` | عمليات داخلية مفصلة | -| `info` | عمليات عادية | -| `warn` | مشاكل قابلة للاسترداد | -| `error` | فشل يستلزم الاهتمام | - -### سجلات JSON المهيكلة - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/baradb.log \ -./build/baradadb -``` - -## لوحة Grafana - -استيراد معرف اللوحة `baradb-001` أو استخدام JSON في `monitoring/grafana-dashboard.json`. - -اللوحات الرئيسية: -- الاستعلامات في الثانية -- نسب مئوية لتأخير الاستعلام (p50, p95, p99) -- حجم التخزين وعدد SSTable -- معدل إصابة ذاكرة التخزين المؤقت -- الاتصالات النشطة -- معدل المعاملات -- معدل الأخطاء - -## حل المشكلات بالمقاييس - -| العَرَض | المقاييس | الإجراء | -|---------|----------|---------| -| استعلامات بطيئة | `baradb_queries_duration_seconds` | فحص معدل إصابة ذاكرة التخزين المؤقت، إضافة فهارس | -| ذاكرة عالية | `process_resident_memory_bytes` | تقليل أحجام memtable/cache | -| نمو التخزين | `baradb_storage_lsm_size_bytes` | تشغيل الضغط اليدوي | -| أخطاء الاتصال | `baradb_active_connections` | زيادة تجمع الاتصالات أو إضافة العقد | \ No newline at end of file diff --git a/docs/ar/performance.md b/docs/ar/performance.md deleted file mode 100644 index 0c4f463..0000000 --- a/docs/ar/performance.md +++ /dev/null @@ -1,68 +0,0 @@ -# دليل الأداء - -## منهجية المعايير - -جميع المعايير تعمل بـ: -- **المترجم**: Nim 2.2.0 مع `-d:release --opt:speed` -- **CPU**: AMD Ryzen 9 5900X (12 نواة / 24 خيط) -- **الذاكرة**: 64 GB DDR4-3600 -- **التخزين**: Samsung 980 Pro NVMe SSD - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## معايير محركات التخزين - -### LSM-Tree - -| المقاييس | القيمة | -|----------|--------| -| إنتاجية الكتابة | ~580,000 ops/s | -| إنتاجية القراءة | ~720,000 ops/s | -| متوسط تأخير الكتابة | 1.7 µs | -| متوسط تأخير القراءة | 1.4 µs | - -### فهرس B-Tree - -| المقاييس | القيمة | -|----------|--------| -| إنتاجية الإدراج | ~1,200,000 ops/s | -| إنتاجية البحث النقطي | ~1,500,000 ops/s | - -## معايير المحرك المتجهي - -### فهرس HNSW - -| المقاييس | القيمة | -|----------|--------| -| الإدراج (dim=128) | ~45,000 vectors/s | -| البحث top-10 (n=100K) | ~8 ms | - -المعلمات: `M=16`, `efConstruction=200`, `efSearch=64`. - -## دليل الضبط - -### لأحمال الكتابة الثقيلة - -```bash -BARADB_MEMTABLE_SIZE_MB=256 -BARADB_WAL_SYNC_INTERVAL_MS=10 -BARADB_COMPACTION_INTERVAL_MS=30000 -``` - -### لأحمال القراءة الثقيلة - -```bash -BARADB_CACHE_SIZE_MB=1024 -BARADB_BLOOM_BITS_PER_KEY=10 -BARADB_COMPACTION_INTERVAL_MS=120000 -``` - -### للبحث المتجهي - -```bash -BARADB_VECTOR_EF_CONSTRUCTION=200 -BARADB_VECTOR_EF_SEARCH=128 -BARADB_VECTOR_M=32 -``` \ No newline at end of file diff --git a/docs/ar/protocol.md b/docs/ar/protocol.md deleted file mode 100644 index 537221b..0000000 --- a/docs/ar/protocol.md +++ /dev/null @@ -1,67 +0,0 @@ -# مرجع البروتوكول - -يدعم BaraDB بروتوكولات متعددة للتواصل مع العملاء: -- **Binary Wire Protocol** — عالي الأداء، منخفض التأخير -- **HTTP/REST API** — لغةagnostic، سهل التصحيح -- **WebSocket** — الدفق و pub/sub - -## Binary Wire Protocol - -يستخدم ترميز big-endian لجميع القيم متعددة البايت. - -### دورة الاتصال - -``` -Client Server - | | - |─── TCP connect ──────────────>| - |─── Auth message ─────────────>| - |<── Auth_OK / Error ───────────| - |─── Query message ────────────>| - |<── Data / Complete / Error ───| -``` - -### تنسيق الرسالة - -``` -┌─────────────┬─────────────┬─────────────┬─────────────────────┐ -│ Length │ Type │ Sequence │ Payload │ -│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ -└─────────────┴─────────────┴─────────────┴─────────────────────┘ -``` - -### أنواع الرسائل - -| النوع | ID | الوصف | -|-------|----|-------| -| Query | 0x01 | تنفيذ استعلام | -| Insert | 0x02 | إدراج بيانات | -| Update | 0x03 | تحديث بيانات | -| Delete | 0x04 | حذف بيانات | -| Ready | 0x05 | جاهز للامر التالي | -| Error | 0x06 | استجابة خطأ | - -## HTTP/REST API - -Base URL: `http://localhost:9470/api/v1` - -### نقاط النهاية - -#### Health - -```http -GET /health -``` - -#### استعلام - -```http -POST /query -{ - "query": "SELECT * FROM users" -} -``` - -## WebSocket Protocol - -URL: `ws://localhost:9471` \ No newline at end of file diff --git a/docs/ar/quickstart.md b/docs/ar/quickstart.md deleted file mode 100644 index 8cab283..0000000 --- a/docs/ar/quickstart.md +++ /dev/null @@ -1,99 +0,0 @@ -# دليل البداية السريعة لـ BaraDB - -## تشغيل الخادم - -```bash -./build/baradadb -``` - -الخادم يبدأ افتراضياً على `localhost:9470`. - -## الاتصال عبر CLI - -```bash -./build/baradadb --shell -``` - -## العمليات الأساسية - -### إنشاء المخطط - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; -``` - -### إدراج البيانات - -```sql -INSERT Person { name := 'Alice', age := 30 }; -``` - -### استعلام البيانات - -```sql -SELECT name, age FROM Person WHERE age > 18; -``` - -### تحديث البيانات - -```sql -UPDATE Person SET age = 31 WHERE name = 'Alice'; -``` - -### حذف البيانات - -```sql -DELETE FROM Person WHERE name = 'Bob'; -``` - -## الاستعلامات المتقدمة - -### JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -### CTE - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## البحث المتجهي - -```sql -INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] }; -SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10; -``` - -## عمليات الرسم البياني - -```sql -MATCH (p:Person)-[:KNOWS]->(other:Person) -WHERE p.name = 'Alice' -RETURN other.name; -``` - -## HTTP/REST API - -```bash -curl http://localhost:9470/api/users -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 30}' -``` - -## الخطوات التالية - -- [مرجع BaraQL](baraql.md) -- [محركات التخزين](storage.md) -- [نظرة عامة على البنية](architecture.md) \ No newline at end of file diff --git a/docs/ar/schema.md b/docs/ar/schema.md deleted file mode 100644 index cf7fe63..0000000 --- a/docs/ar/schema.md +++ /dev/null @@ -1,46 +0,0 @@ -# نظام المخطط - -يستخدم BaraDB تصميم schema-first مع وراثة النوع والهجرة التلقائية. - -## تحديد الأنواع - -```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) -``` - -## وراثة النوع - -```nim -let employee = newType("Employee") -employee.setBases(@["Person"]) -employee.addProperty("department", "str") -s.addType("default", employee) -``` - -## عمليات المخطط - -### Diff - -```nim -let diff = s.diff(oldSchema, newSchema) -``` - -## أنواع الخصائص - -| النوع | الوصف | -|-------|-------| -| `str` | سلسلة | -| `int32` | عدد صحيح 32 بت | -| `int64` | عدد صحيح 64 بت | -| `float32` | فاصلة عائمة 32 بت | -| `float64` | فاصلة عائمة 64 بت | -| `bool` | منطقي | -| `datetime` | تاريخ/وقت | -| `bytes` | بيانات ثنائية | \ No newline at end of file diff --git a/docs/ar/security.md b/docs/ar/security.md deleted file mode 100644 index acb6b7e..0000000 --- a/docs/ar/security.md +++ /dev/null @@ -1,76 +0,0 @@ -# دليل الأمان - -## تشفير TLS/SSL - -تدعم BaraDB TLS 1.3 لجميع البروتوكولات. إذا لم يتم توفير شهادة، ينشئ الخادم شهادة ذاتية التوقيع تلقائياً عند البدء. - -### استخدام شهادات مخصصة - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_CERT_FILE=/etc/baradb/server.crt \ -BARADB_KEY_FILE=/etc/baradb/server.key \ -./build/baradadb -``` - -### إنشاء شهادة ذاتية التوقيع - -```bash -openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ - -days 365 -nodes -subj "/CN=localhost" -``` - -## المصادقة - -### المصادقة المبنية على JWT - -تستخدم BaraDB JWT مع توقيع HMAC-SHA256. - -### تمكين المصادقة - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -### التحكم في الوصول القائم على الأدوار - -| الدور | الأذونات | -|-------|----------| -| `admin` | وصول كامل | -| `write` | قراءة + كتابة | -| `read` | قراءة فقط | -| `monitor` | المقاييس والصحة فقط | - -## تحديد المعدل - -منع إساءة الاستخدام: - -```nim -var rl = newRateLimiter( - rlaTokenBucket, - globalRate = 10000, - perClientRate = 1000, - burstSize = 100 -) -``` - -## أمان الشبكة - -### عنوان الربط - -```bash -BARADB_ADDRESS=0.0.0.0 ./build/baradadb -``` - -## قائمة التحقق الأمنية - -- [ ] تغيير سر JWT الافتراضي -- [ ] تمكين TLS بشهادات صالحة -- [ ] الربط بواجهات محددة -- [ ] تمكين المصادقة في الإنتاج -- [ ] تكوين تحديد المعدل -- [ ] تمكين سجل التدقيق -- [ ] تشفير البيانات في حالة السكون -- [ ] تشغيل BaraDB كمستخدم غير root \ No newline at end of file diff --git a/docs/ar/storage.md b/docs/ar/storage.md deleted file mode 100644 index 5f73d4b..0000000 --- a/docs/ar/storage.md +++ /dev/null @@ -1,67 +0,0 @@ -# محركات التخزين - -توفر BaraDB محركات تخزين متعددة محسنة لأنماط الوصول المختلفة. - -## LSM-Tree (مفتاح-قيمة) - -محرك التخزين الأساسي المحسن للكتابة مع بنية log-only إلحاقية. - -### الاستخدام - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key1", cast[seq[byte]]("value1")) -let (found, value) = db.get("key1") -db.close() -``` - -### المكونات - -- **MemTable**: مخزن مؤقت مرتب في الذاكرة -- **WAL**: سجل write-ahead للدائمة -- **SSTable**: جداول السلاسل المرتبة على القرص -- **Bloom Filter**: بنية احتمالية للبحث السلبي السريع -- **الضغط**: استراتيجية ذات طبقات بحجم مع إدارة المستويات -- **ذاكرة الصفحة**: ذاكرة مؤقتة LRU مع تتبع معدل الإصابة - -## فهرس B-Tree - -فهرس مرتب للبحث بالنطاق والبحث النقطي. - -### الاستخدام - -```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) - -يضمن دائمة عمليات الكتابة. - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append("txn1", "SET key1 value1") -wal.flush() -``` - -## Bloom Filter - -هيكل بيانات احتمالي للبحث السلبي السريع. - -```nim -import barabadb/storage/bloom - -var filter = newBloomFilter(10000, 0.01) -filter.add("key1") -if filter.mightContain("key1"): - echo "ربما موجود" -``` \ No newline at end of file diff --git a/docs/ar/transactions.md b/docs/ar/transactions.md deleted file mode 100644 index 2d2a3b5..0000000 --- a/docs/ar/transactions.md +++ /dev/null @@ -1,47 +0,0 @@ -# المعاملات و MVCC - -MVCC (تحكم التزامن متعدد الإصدارات) مع عزل اللقطة واكتشاف الجمود. - -## الاستخدام - -```nim -import barabadb/core/mvcc - -var tm = newTxnManager() -let txn = tm.beginTxn() - -discard tm.write(txn, "key1", cast[seq[byte]]("value1")) -discard tm.write(txn, "key2", cast[seq[byte]]("value2")) - -tm.savepoint(txn) -discard tm.write(txn, "key3", cast[seq[byte]]("value3")) -discard tm.rollbackToSavepoint(txn) - -discard tm.commit(txn) -``` - -## عزل المعاملات - -تستخدم BaraDB **عزل اللقطة**: -- القراء لا يحظرون الكتاب -- الكتاب لا يحظرون القراء -- كل معاملة ترى لقطة متسقة - -## اكتشاف الجمود - -```nim -import barabadb/core/deadlock - -var detector = newDeadlockDetector() -if detector.detectCycle(txn1, txn2): - echo "تم اكتشاف الجمود!" -``` - -## التحقق الرسمي - -تم تحديد بروتوكول MVCC/Snapshot Isolation رسمياً في TLA+: - -```bash -cd formal-verification -java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla -``` \ No newline at end of file diff --git a/docs/ar/troubleshooting.md b/docs/ar/troubleshooting.md deleted file mode 100644 index 5ff728a..0000000 --- a/docs/ar/troubleshooting.md +++ /dev/null @@ -1,81 +0,0 @@ -# دليل حل المشكلات - -## مشاكل التثبيت - -### Nim غير موجود - -```bash -curl https://nim-lang.org/choosenim/init.sh -sSf | sh -``` - -### خطأ تجميع SSL - -```bash -nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim -``` - -### تبعيات مفقودة - -```bash -nimble install -d -y -``` - -## مشاكل وقت التشغيل - -### المنفذ قيد الاستخدام - -```bash -BARADB_PORT=5433 ./build/baradadb -``` - -### تم رفض الإذن - -```bash -mkdir -p ./data -chmod 755 ./data -``` - -### ذاكرة غير كافية - -```bash -BARADB_MEMTABLE_SIZE_MB=32 \ -BARADB_CACHE_SIZE_MB=128 \ -./build/baradadb -``` - -## مشاكل الاستعلام - -### خطأ في الصياغة - -```sql -SELECT name, age FROM users WHERE age > 18; -``` - -### الجدول غير موجود - -```sql -CREATE TYPE User { name: str, age: int32 }; -``` - -## مشاكل الاتصال - -### تم رفض الاتصال - -```bash -./build/baradadb -sudo ufw allow 9472 -``` - -## مشاكل الأداء - -### استعلامات بطيئة - -1. إضافة فهارس: `CREATE INDEX idx_users_name ON users(name);` -2. استخدام LIMIT -3. زيادة ذاكرة التخزين المؤقت: `BARADB_CACHE_SIZE_MB=1024` - -## وضع التصحيح - -```bash -BARADB_LOG_LEVEL=debug ./build/baradadb -``` \ No newline at end of file diff --git a/docs/ar/udf.md b/docs/ar/udf.md deleted file mode 100644 index 5f22b9b..0000000 --- a/docs/ar/udf.md +++ /dev/null @@ -1,47 +0,0 @@ -# الدوال المحددة من المستخدم - -توسيع BaraQL بالدوال المخصصة. - -## الاستخدام - -```nim -import barabadb/query/udf - -var reg = newUDFRegistry() - -reg.registerStdlib() - -reg.register("greet", @[UDFParam(name: "name", typeName: "str")], - "str", proc(args: seq[Value]): Value = - return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) -``` - -## دوال المكتبة القياسية - -| الدالة | الوصف | مثال | -|--------|-------|------| -| `abs(n)` | القيمة المطلقة | `abs(-5)` → 5 | -| `sqrt(n)` | الجذر التربيعي | `sqrt(16)` → 4 | -| `pow(n, e)` | الأس | `pow(2, 3)` → 8 | -| `lower(s)` | حروف صغيرة | `lower('ABC')` → 'abc' | -| `upper(s)` | حروف كبيرة | `upper('abc')` → 'ABC' | -| `len(s)` | الطول | `len('hello')` → 5 | -| `trim(s)` | إزالة المسافات | `trim(' hello ')` → 'hello' | - -## تسجيل الدالة - -```nim -reg.register( - name: "my_function", - params: @[UDFParam(name: "arg1", typeName: "str")], - returnType: "str", - body: proc(args: seq[Value]): Value = - result = Value(kind: vkString, strVal: "") -) -``` - -## استخدام UDF في الاستعلامات - -```sql -SELECT greet(name) FROM users; -``` \ No newline at end of file diff --git a/docs/ar/vector.md b/docs/ar/vector.md deleted file mode 100644 index e72609d..0000000 --- a/docs/ar/vector.md +++ /dev/null @@ -1,65 +0,0 @@ -# محرك البحث المتجهي - -فهارس HNSW و IVF-PQ للبحث عن التشابه. - -## الاستخدام - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) -``` - -## أنواع الفهارس - -### HNSW - -رسم بياني Small World قابل للملاحة هرمي للبحث عن أقرب الجيران. - -```nim -var hnsw = newHNSWIndex( - dimensions = 128, - m = 16, - efConstruction = 200, - efSearch = 100 -) -``` - -### IVF-PQ - -فهرس ملف مقلوب مع تكميم المنتج. - -```nim -var ivfpq = newIVFPQIndex( - dimensions = 128, - numCentroids = 256, - subQuantizers = 8 -) -``` - -## مقاييس المسافة - -| المقياس | الوصف | -|---------|-------| -| `cosine` | تشابه جيب التمام | -| `euclidean` | مسافة L2 | -| `dotproduct` | تشابه المنتج النقطي | -| `manhattan` | مسافة L1 | - -## التكميم - -```nim -let scalar = scalarQuantize(data, bits = 8) -let pq = productQuantize(data, subVectors = 8, bits = 8) -``` - -## تسريع SIMD - -```nim -import barabadb/vector/simd - -let dist = simdCosineDistance(vec1, vec2) -``` \ No newline at end of file diff --git a/docs/bg/index.md b/docs/bg/index.md index 78bbd5a..6e08d5d 100644 --- a/docs/bg/index.md +++ b/docs/bg/index.md @@ -6,12 +6,6 @@ - [English](../en/) - [Български (Bulgarian)](../bg/) -- [Deutsch (German)](../de/) -- [Русский (Russian)](../ru/) -- [فارسی (Farsi)](../fa/) -- [中文 (Chinese)](../zh/) -- [Türkçe (Turkish)](../tr/) -- [العربية (Arabic)](../ar/) --- @@ -61,4 +55,4 @@ --- -*За да добавите нов език, създайте нова папка в `docs/` с езиковия код (напр. `docs/de/`).* +*За да добавите нов език, създайте нова папка в `docs/` с езиковия код.* diff --git a/docs/de/api-binary.md b/docs/de/api-binary.md deleted file mode 100644 index 142424c..0000000 --- a/docs/de/api-binary.md +++ /dev/null @@ -1,74 +0,0 @@ -# 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 deleted file mode 100644 index f6fac80..0000000 --- a/docs/de/api-http.md +++ /dev/null @@ -1,91 +0,0 @@ -# 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 deleted file mode 100644 index 39562f0..0000000 --- a/docs/de/api-websocket.md +++ /dev/null @@ -1,120 +0,0 @@ -# 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 deleted file mode 100644 index 5717735..0000000 --- a/docs/de/architecture.md +++ /dev/null @@ -1,152 +0,0 @@ -# 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 deleted file mode 100644 index f09a489..0000000 --- a/docs/de/backup.md +++ /dev/null @@ -1,199 +0,0 @@ -# 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/baraql.md b/docs/de/baraql.md deleted file mode 100644 index 8ea1f05..0000000 --- a/docs/de/baraql.md +++ /dev/null @@ -1,114 +0,0 @@ -# BaraQL — Abfragesprache-Referenz - -BaraQL ist eine SQL-kompatible Abfragesprache mit Erweiterungen für Graph-, Vektor- und Dokumentoperationen. - -## Datentypen - -| Typ | Beschreibung | Beispiel | -|------|-------------|---------| -| `null` | Nullwert | `null` | -| `bool` | Boolean | `true`, `false` | -| `int64` | 64-bit Ganzzahl | `42` | -| `float64` | 64-bit Fließkomma | `3.14` | -| `str` | UTF-8 String | `'hello'` | -| `vector(n)` | Float32 Vektor | `VECTOR(768)` | -| `json` | JSON-Dokument | `{"key": "value"}` | - -## Grundlegende Abfragen - -```sql -SELECT * FROM users; -SELECT name, age FROM users WHERE age > 18; -SELECT * FROM users ORDER BY age DESC LIMIT 10; -``` - -## Vektor-Operationen - -```sql --- Distanzberechnungen -SELECT cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items; -SELECT embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items; - --- Hybride Suche -SELECT hybrid_search('query', embedding, content, 10) AS result; -``` - -## Graph-Operationen - -```sql -CREATE GRAPH social; -DROP GRAPH social; - --- Traversierung -SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m) - ALGORITHM bfs START 1 - COLUMNS (id, node_label)); - --- PageRank -SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank - COLUMNS (id, node_label, rank)); - --- Community Detection -SELECT * FROM GRAPH_TABLE(social ALGORITHM community - COLUMNS (id, node_label, community)); -``` - -## AI-Funktionen - -```sql --- Text in Chunks zerlegen -SELECT chunk('Langer Text...', 1024, 128) AS result; - --- Embedding generieren -SELECT embed_text('Suchtext') AS result; - --- Natural Language → SQL -SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result; - --- Schema-Prompt für LLM -SELECT schema_prompt('users') AS result; - --- Cypher-Übersetzung -SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label') AS result; - --- Knotenähnlichkeit -SELECT similarity_nodes('social', 'jaccard') AS result; - --- Graph-Embeddings -SELECT node2vec_embed('social', 64) AS result; -``` - -## Joins - -```sql -SELECT u.name, o.amount -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -## Aggregation - -```sql -SELECT department, COUNT(*), AVG(salary) -FROM employees -GROUP BY department -HAVING COUNT(*) > 5; -``` - -## Index-Erstellung - -```sql -CREATE INDEX idx_name ON users(name) USING btree; -CREATE INDEX idx_vec ON docs(embedding) USING hnsw; -CREATE INDEX idx_fts ON docs(content) USING fts; -``` - -## Multi-Tenant / RLS - -```sql -CREATE POLICY tenant_policy ON orders -FOR ALL USING (tenant_id = current_setting('app.tenant_id')); - -SET app.tenant_id = 'company-a'; -SELECT * FROM orders; -- Automatisch gefiltert -``` diff --git a/docs/de/btree.md b/docs/de/btree.md deleted file mode 100644 index 388155a..0000000 --- a/docs/de/btree.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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 deleted file mode 100644 index 34c425e..0000000 --- a/docs/de/changelog.md +++ /dev/null @@ -1,247 +0,0 @@ -# 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.6** — 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.6 -- **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 deleted file mode 100644 index 3c6fe34..0000000 --- a/docs/de/clients.md +++ /dev/null @@ -1,285 +0,0 @@ -# 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 deleted file mode 100644 index de6db0e..0000000 --- a/docs/de/columnar.md +++ /dev/null @@ -1,58 +0,0 @@ -# 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 deleted file mode 100644 index e6ea6b2..0000000 --- a/docs/de/configuration.md +++ /dev/null @@ -1,217 +0,0 @@ -# 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.6 — 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 deleted file mode 100644 index aa25287..0000000 --- a/docs/de/crossmodal.md +++ /dev/null @@ -1,218 +0,0 @@ -# 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 deleted file mode 100644 index f195efb..0000000 --- a/docs/de/deployment.md +++ /dev/null @@ -1,247 +0,0 @@ -# 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 deleted file mode 100644 index f5f45f5..0000000 --- a/docs/de/distributed.md +++ /dev/null @@ -1,110 +0,0 @@ -# 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 deleted file mode 100644 index face19c..0000000 --- a/docs/de/docker.md +++ /dev/null @@ -1,191 +0,0 @@ -# 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 deleted file mode 100644 index 4d98aa5..0000000 --- a/docs/de/fts.md +++ /dev/null @@ -1,87 +0,0 @@ -# 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/graph.md b/docs/de/graph.md deleted file mode 100644 index 908ef73..0000000 --- a/docs/de/graph.md +++ /dev/null @@ -1,145 +0,0 @@ -# Graph Engine - -Adjazenzlisten-Speicher mit eingebauten Algorithmen für Graph-Traversierung und -Analyse. -Vollständig integriert in den SQL-Executor via `GRAPH_TABLE()`. - -## SQL — Graph DDL - -### Graph erstellen - -```sql -CREATE GRAPH org_chart; -``` - -Erstellt automatisch zwei Tabellen: -- `org_chart_nodes (id INTEGER PRIMARY KEY, node_label TEXT, properties TEXT)` -- `org_chart_edges (source_id INTEGER, dest_id INTEGER, edge_label TEXT, weight REAL)` - -### Graph löschen - -```sql -DROP GRAPH org_chart; -``` - -## SQL — Daten einfügen - -```sql --- Knoten -INSERT INTO org_chart_nodes (id, node_label) VALUES (1, 'CEO'); -INSERT INTO org_chart_nodes (id, node_label) VALUES (2, 'VP'); - --- Kanten -INSERT INTO org_chart_edges (source_id, dest_id, edge_label) VALUES (1, 2, 'manages'); -``` - -Alle INSERTs werden automatisch mit dem nativen Graph-Objekt synchronisiert. - -## SQL — GRAPH_TABLE Abfragen - -### BFS (Breitensuche) - -```sql -SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m) - ALGORITHM bfs - START 1 MAXDEPTH 2 - COLUMNS (id, node_label)); -``` - -### DFS (Tiefensuche) - -```sql -SELECT * FROM GRAPH_TABLE(org_chart MATCH (n)-[r]->(m) - ALGORITHM dfs START 1 - COLUMNS (id, node_label)); -``` - -### PageRank - -```sql -SELECT id, node_label, rank FROM GRAPH_TABLE(org_chart - ALGORITHM pagerank - COLUMNS (id, node_label, rank)) -ORDER BY rank DESC; -``` - -### Community Detection (Louvain) - -```sql -SELECT id, node_label, community FROM GRAPH_TABLE(org_chart - ALGORITHM community - COLUMNS (id, node_label, community)); -``` - -### Kürzester Pfad (Shortest Path) - -```sql -SELECT * FROM GRAPH_TABLE(org_chart - ALGORITHM shortest_path - START 1 END 3 - COLUMNS (id, node_label)); -``` - -### Dijkstra (gewichtete kürzeste Pfade) - -```sql -SELECT * FROM GRAPH_TABLE(org_chart - ALGORITHM dijkstra START 1 - COLUMNS (id, node_label, distance)); -``` - -## SQL-Funktionen - -### Knotenähnlichkeit - -```sql --- Jaccard-Ähnlichkeit zwischen allen Knotenpaaren -SELECT similarity_nodes('social', 'jaccard') AS result; - --- Adamic-Adar-Ähnlichkeit -SELECT similarity_nodes('social', 'adamic_adar') AS result; -``` - -### Node2Vec Embeddings - -```sql --- Graphstruktur-Embeddings generieren (64 Dimensionen) -SELECT node2vec_embed('social', 64) AS result; -``` - -## Cypher-Kompatibilität - -```sql --- Cypher-Syntax automatisch nach GRAPH_TABLE übersetzen -SELECT cypher('MATCH (a)-[r]->(b) WHERE a.node_label = ''CEO'' RETURN b.node_label') AS result; -``` - -## Algorithmen - -| Algorithmus | Beschreibung | SQL | -|-------------|--------------|-----| -| `bfs` | Breitensuche | `ALGORITHM bfs` | -| `dfs` | Tiefensuche | `ALGORITHM dfs` | -| `dijkstra` | Gewichtete kürzeste Pfade | `ALGORITHM dijkstra` | -| `pageRank` | Knoten-Wichtigkeit | `ALGORITHM pagerank` | -| `louvain` | Community Detection | `ALGORITHM community` | -| `shortestPath` | Kürzester Pfad | `ALGORITHM shortest_path START X END Y` | -| `similarityNodes` | Knotenähnlichkeit | `similarity_nodes()` | -| `node2vec` | Graph Embeddings | `node2vec_embed()` | - -## Native Nim API - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -let communities = louvain(g) -let similarities = g.similarityNodes(smJaccard) -let embeddings = g.node2vec(64, 10, 5) -``` diff --git a/docs/de/index.md b/docs/de/index.md deleted file mode 100644 index 2598791..0000000 --- a/docs/de/index.md +++ /dev/null @@ -1,64 +0,0 @@ -# BaraDB Dokumentation - -**Eine multimodale Datenbank-Engine — 100% Nim, null Abhängigkeiten.** - -## Sprachen - -- [English](../en/) -- [Български (Bulgarisch)](../bg/) -- [Deutsch (German)](../de/) -- [Русский (Russisch)](../ru/) -- [فارسی (Farsi)](../fa/) -- [中文 (Chinesisch)](../zh/) -- [Türkçe (Türkisch)](../tr/) -- [العربية (Arabisch)](../ar/) - ---- - -## Schnellstart - -- [Installation](installation.md) -- [Schnellstart](quickstart.md) -- [Architektur](architecture.md) -- [Konfiguration](configuration.md) - -## Kernkonzepte - -- [BaraQL Abfragesprache](baraql.md) -- [Speicher-Engines](storage.md) -- [Schema System](schema.md) - -## Engines - -- [LSM-Tree Speicher](lsm.md) -- [B-Tree Index](btree.md) -- [Vektor-Suche](vector.md) -- [Graph Engine](graph.md) -- [Volltext-Suche](fts.md) -- [Spaltenbasierte Speicherung](columnar.md) - -## API & Clients - -- [Client SDKs](clients.md) -- [Binärprotokoll](api-binary.md) -- [HTTP/REST API](api-http.md) -- [MCP Server](mcp.md) - -## Betrieb - -- [Performance](performance.md) -- [Sicherheit](security.md) -- [Monitoring](monitoring.md) -- [Backup & Recovery](backup.md) -- [Fehlerbehebung](troubleshooting.md) - -## Erweitert - -- [Transaktionen & MVCC](transactions.md) -- [Verteilte Systeme](distributed.md) -- [Docker Deployment](docker.md) -- [Änderungsprotokoll](changelog.md) - ---- - -*Um eine neue Sprache hinzuzufügen, erstellen Sie einen neuen Ordner in `docs/` mit dem Sprachcode (z.B. `docs/de/`).* diff --git a/docs/de/installation.md b/docs/de/installation.md deleted file mode 100644 index 8bc79c1..0000000 --- a/docs/de/installation.md +++ /dev/null @@ -1,57 +0,0 @@ -# BaraDB — Installation - -## Voraussetzungen - -- **Nim >= 2.2.0** (`curl https://nim-lang.org/choosenim/init.sh -sSf | sh`) -- **Git** -- **OpenSSL** (für TLS) - -## Aus dem Quellcode bauen - -```bash -git clone https://github.com/katehonz/barabaDB.git -cd barabadb -nimble build_release -``` - -Die Binärdateien werden im `build/` Verzeichnis erstellt: -- `build/baradadb` — Datenbank-Server (TCP + HTTP) -- `build/baramcp` — MCP Server für AI-Agenten - -## Debug-Build - -```bash -nimble build_debug -``` - -## Tests ausführen - -```bash -nimble test -``` - -## Docker - -```bash -docker compose up -d -``` - -## Verifizierung - -```bash -./build/baradadb --version -# BaraDB v1.1.6 — Multimodal Database Engine - -./build/baramcp --data-dir ./data & -echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./build/baramcp -``` - -## Manuelle Kompilierung - -```bash -# Server -nim c -d:release --opt:speed -o:build/baradadb src/baradadb.nim - -# MCP Server -nim c -d:release --opt:speed -o:build/baramcp src/baramcp.nim -``` diff --git a/docs/de/lsm.md b/docs/de/lsm.md deleted file mode 100644 index 4cb8a59..0000000 --- a/docs/de/lsm.md +++ /dev/null @@ -1,64 +0,0 @@ -# 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/mcp.md b/docs/de/mcp.md deleted file mode 100644 index 19878d1..0000000 --- a/docs/de/mcp.md +++ /dev/null @@ -1,108 +0,0 @@ -# MCP Server (Model Context Protocol) - -BaraDB enthält einen eingebauten MCP-Server, der es AI-Agenten (Claude, Cursor, etc.) ermöglicht, direkt mit der Datenbank zu interagieren. - -## Schnellstart - -```bash -./build/baramcp --data-dir ./data -``` - -Der Server startet im STDIO-Modus und akzeptiert JSON-RPC 2.0 Nachrichten. - -## Verfügbare Tools - -### 1. `query` — SQL ausführen - -```json -{ - "name": "query", - "arguments": { - "sql": "SELECT * FROM users WHERE age > ?", - "params": [25], - "tenant_id": "company-a", - "user_id": "alice" - } -} -``` - -Parameterisierte Abfragen mit `?`-Platzhaltern. Multi-Tenant-Support über `tenant_id` und `user_id`. - -### 2. `vector_search` — Semantische Suche - -```json -{ - "name": "vector_search", - "arguments": { - "table": "docs", - "column": "embedding", - "query_vector": [0.1, 0.2, 0.3], - "k": 5, - "metric": "cosine", - "tenant_id": "company-a" - } -} -``` - -Unterstützte Metriken: `cosine`, `euclidean`, `dot_product`, `manhattan`. - -### 3. `schema_inspect` — Schema erkunden - -```json -{ - "name": "schema_inspect", - "arguments": { - "table": "users", - "tenant_id": "company-a" - } -} -``` - -Gibt Tabellen, Spalten, Typen, Primärschlüssel, Fremdschlüssel, Indizes und RLS-Policies zurück. - -## Konfiguration in Claude Desktop - -```json -{ - "mcpServers": { - "baradb": { - "command": "/pfad/zu/build/baramcp", - "args": ["--data-dir", "/pfad/zu/daten"] - } - } -} -``` - -## Konfiguration in Cursor - -```json -{ - "mcpServers": { - "baradb": { - "command": "/pfad/zu/build/baramcp", - "args": ["--data-dir", "~/.baradb/data"] - } - } -} -``` - -## Multi-Tenant Isolation - -Jede MCP-Anfrage kann `tenant_id` und `user_id` enthalten. Diese werden als Session-Variablen gesetzt: - -- `app.tenant_id` — für RLS-Filterung -- `app.user_id` — für `current_user`-Referenzen - -RLS-Policies filtern die Daten automatisch basierend auf diesen Variablen. - -## JSON-RPC 2.0 Protokoll - -Der Server verwendet JSON-RPC 2.0 über STDIO: - -```json -// Anfrage -{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {...}} - -// Antwort -{"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "..."}]}} -``` diff --git a/docs/de/monitoring.md b/docs/de/monitoring.md deleted file mode 100644 index 74ca43c..0000000 --- a/docs/de/monitoring.md +++ /dev/null @@ -1,258 +0,0 @@ -# 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 deleted file mode 100644 index d23267f..0000000 --- a/docs/de/performance.md +++ /dev/null @@ -1,174 +0,0 @@ -# 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 deleted file mode 100644 index 47ebbf4..0000000 --- a/docs/de/protocol.md +++ /dev/null @@ -1,240 +0,0 @@ -# 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/quickstart.md b/docs/de/quickstart.md deleted file mode 100644 index 074effa..0000000 --- a/docs/de/quickstart.md +++ /dev/null @@ -1,134 +0,0 @@ -# BaraDB — Schnellstart - -## Server starten - -```bash -./build/baradadb -``` - -Der Server startet standardmäßig auf `localhost:9470`. - -## Verbindung via CLI - -```bash -./build/baradadb --shell -``` - -## MCP Server (AI Agenten) - -```bash -./build/baramcp --data-dir ./data -``` - -Der MCP Server startet im STDIO-Modus und stellt 3 Tools für AI-Agenten bereit: `query`, `vector_search`, `schema_inspect`. - -## Grundlegende Operationen - -### Tabelle erstellen - -```sql -CREATE TABLE users ( - id INTEGER PRIMARY KEY, - name TEXT, - email TEXT, - age INTEGER -); -``` - -### Daten einfügen - -```sql -INSERT INTO users (id, name, email, age) VALUES (1, 'Alice', 'alice@test.com', 30); -INSERT INTO users (id, name, email, age) VALUES (2, 'Bob', 'bob@test.com', 25); -``` - -### Daten abfragen - -```sql -SELECT name, age FROM users WHERE age > 18; -``` - -### Indizes erstellen - -```sql --- BTree Index -CREATE INDEX idx_name ON users(name) USING btree; - --- Volltext-Index -CREATE INDEX idx_email_fts ON users(email) USING fts; - --- Vektor-Index -CREATE INDEX idx_vec ON items(embedding) USING hnsw; -``` - -## Vector Search - -```sql -CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768)); -CREATE INDEX docs_vec ON docs(embedding) USING hnsw; - --- Ähnlichkeitssuche -SELECT id, cosine_distance(embedding, '[0.1, 0.2, ...]') AS dist -FROM docs ORDER BY dist ASC LIMIT 10; -``` - -## Graph Engine - -```sql -CREATE GRAPH social; -INSERT INTO social_nodes (id, node_label) VALUES (1, 'Alice'), (2, 'Bob'); -INSERT INTO social_edges (source_id, dest_id) VALUES (1, 2); - --- BFS Traversal -SELECT * FROM GRAPH_TABLE(social MATCH (n)-[r]->(m) ALGORITHM bfs COLUMNS (id, node_label)); - --- PageRank -SELECT * FROM GRAPH_TABLE(social ALGORITHM pagerank COLUMNS (id, node_label, rank)); - --- Community Detection (Louvain) -SELECT * FROM GRAPH_TABLE(social ALGORITHM community COLUMNS (id, node_label, community)); - --- Kürzester Pfad -SELECT * FROM GRAPH_TABLE(social ALGORITHM shortest_path START 1 END 2 COLUMNS (id, node_label)); - --- Knoten-Ähnlichkeit (Jaccard) -SELECT similarity_nodes('social', 'jaccard') AS result; -``` - -## AI Pipeline - -```sql --- Text in Chunks zerlegen -SELECT chunk('Langer Text hier...', 1024, 128) AS result; - --- Embedding generieren (mit konfiguriertem externen Service) -SELECT embed_text('Suchanfrage') AS result; - --- Schema-Prompt für LLM generieren -SELECT schema_prompt('users') AS result; - --- Natural Language → SQL (mit konfiguriertem LLM) -SELECT nl_to_sql('Zeige alle Benutzer über 25', 'users') AS result; - --- Cypher zu BaraQL übersetzen -SELECT cypher('MATCH (a)-[r]->(b) RETURN a.node_label, b.node_label') AS result; -``` - -## HTTP/REST API - -```bash -curl -X POST http://localhost:9470/query \ - -H "Content-Type: application/json" \ - -d '{"query": "SELECT * FROM users"}' -``` - -## Konfiguration - -```bash -# Umgebungsvariablen -export BARADB_DATA_DIR=./data -export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings -export BARADB_EMBED_MODEL=nomic-embed-text -export BARADB_LLM_ENDPOINT=http://localhost:11434/api/generate -export BARADB_LLM_MODEL=llama3 -``` diff --git a/docs/de/schema.md b/docs/de/schema.md deleted file mode 100644 index 6f0486e..0000000 --- a/docs/de/schema.md +++ /dev/null @@ -1,55 +0,0 @@ -# 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 deleted file mode 100644 index ee5b484..0000000 --- a/docs/de/security.md +++ /dev/null @@ -1,184 +0,0 @@ -# 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 deleted file mode 100644 index 79df0ad..0000000 --- a/docs/de/storage.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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 deleted file mode 100644 index 4fb5ab3..0000000 --- a/docs/de/transactions.md +++ /dev/null @@ -1,78 +0,0 @@ -# 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 deleted file mode 100644 index c3dcb67..0000000 --- a/docs/de/troubleshooting.md +++ /dev/null @@ -1,335 +0,0 @@ -# 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 deleted file mode 100644 index a2ece38..0000000 --- a/docs/de/udf.md +++ /dev/null @@ -1,56 +0,0 @@ -# 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/de/vector.md b/docs/de/vector.md deleted file mode 100644 index aa6ea47..0000000 --- a/docs/de/vector.md +++ /dev/null @@ -1,129 +0,0 @@ -# Vektor-Suche - -Native HNSW und IVF-PQ Indizes für Ähnlichkeitssuche mit vollständiger SQL-Integration. - -## SQL — Vektor-Spalten - -```sql -CREATE TABLE items ( - id INT PRIMARY KEY, - embedding VECTOR(768) -); -``` - -Der `VECTOR(n)`-Typ speichert float32-Arrays mit fester Dimension `n`. - -## Vektoren einfügen - -```sql -INSERT INTO items (id, embedding) VALUES (1, '[0.1, 0.2, 0.3, ...]'); -``` - -## Vektor-Distanzfunktionen - -```sql --- Kosinus-Distanz (0 = identisch, 1 = orthogonal) -SELECT id, cosine_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items; - --- Euklidische / L2 Distanz -SELECT id, euclidean_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items; -SELECT id, embedding <-> '[0.1, 0.2, 0.3]' AS dist FROM items; - --- Inneres Produkt (negativ für Minimierung) -SELECT id, inner_product(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items; - --- Manhattan / L1 Distanz -SELECT id, l1_distance(embedding, '[0.1, 0.2, 0.3]') AS dist FROM items; -``` - -## Vektor-Indizes - -```sql --- HNSW-Index für approximative Nächste-Nachbarn-Suche -CREATE INDEX idx_items_vec ON items(embedding) USING hnsw; - --- Der Index wird bei INSERT und UPDATE automatisch aktualisiert -``` - -## Hybrid RAG Search - -```sql --- Kombinierte Vektor- + Volltext-Suche mit RRF-Reranking -SELECT hybrid_search('AI query', embedding, content, 10) AS result; - --- Gefilterte hybride Suche -SELECT hybrid_search_filtered('AI query', embedding, content, 10, 'category', 'news') AS result; -``` - -## AI Pipeline - -### Text-Chunking - -```sql --- Text in überlappende Chunks zerlegen -SELECT chunk('Langer Text hier...', 1024, 128) AS result; - --- Ergebnis: [{"index":0, "text":"...", "size":124}, ...] -``` - -### Embedding-Generierung - -```sql --- Externen Embedding-Service aufrufen (konfiguriert via Umgebungsvariablen) -SELECT embed_text('Suchtext hier') AS result; -``` - -Umgebungsvariablen für den Embedder: -```bash -export BARADB_EMBED_ENDPOINT=http://localhost:11434/api/embeddings -export BARADB_EMBED_MODEL=nomic-embed-text -``` - -### Auto-Embedding bei INSERT - -Wenn eine VECTOR-Spalte NULL ist, aber eine TEXT-Spalte einen Wert hat, wird das Embedding automatisch generiert (falls ein Embedder konfiguriert ist). - -```sql -CREATE TABLE docs (id INTEGER PRIMARY KEY, content TEXT, embedding VECTOR(768)); -CREATE INDEX docs_vec ON docs(embedding) USING hnsw; - --- embedding wird automatisch gefüllt -INSERT INTO docs (id, content) VALUES (1, 'Dieser Text wird automatisch embedded'); -``` - -## Distanzmetriken - -| Metrik | SQL-Funktion | Beschreibung | -|--------|-------------|-------------| -| `cosine` | `cosine_distance(a, b)` | Kosinus-Distanz | -| `euclidean` | `euclidean_distance(a, b)` / `<->` | L2-Distanz | -| `dotproduct` | `inner_product(a, b)` | Negatives Skalarprodukt | -| `manhattan` | `l1_distance(a, b)` | L1-Distanz | - -## Index-Typen - -### HNSW (Standard) - -```nim -import barabadb/vector/engine -var hnsw = newHNSWIndex(dimensions = 128, m = 16, efConstruction = 200) -``` - -### IVF-PQ - -```nim -var ivfpq = newIVFPQIndex(dimensions = 128, numCentroids = 256, subQuantizers = 8) -``` - -## Native Nim API - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) -let filtered = idx.searchWithFilter(queryVector, k = 10, - filter = proc(meta: Table[string, string]): bool = return "category" in meta) -``` diff --git a/docs/en/changelog.md b/docs/en/changelog.md index b290cd8..45530ee 100644 --- a/docs/en/changelog.md +++ b/docs/en/changelog.md @@ -53,7 +53,7 @@ All notable changes to BaraDB are documented in this file. - **Cypher Compatibility Layer**: - `cypher()` SQL function — translates `MATCH (a)-[r]->(b) RETURN ...` to GRAPH_TABLE - Automatic Cypher → BaraQL conversion -- **German Documentation** — Full documentation set in German (`docs/de/`) +- **Bulgarian Documentation** — Full documentation set in Bulgarian (`docs/bg/`) (replaces removed German, Russian, Arabic, Farsi, Turkish, and Chinese docs) ### Changed diff --git a/docs/fa/api-binary.md b/docs/fa/api-binary.md deleted file mode 100644 index 30d039c..0000000 --- a/docs/fa/api-binary.md +++ /dev/null @@ -1,62 +0,0 @@ -# API پروتکل باینری - -پروتکل سطح پایین برای اتصالات با کارایی بالا. - -## فرمت پیام - -همه پیام‌ها از ترتیب big-endian استفاده می‌کنند: - -``` -┌────────┬────────┬────────┬────────┬─────────────┐ -│ Length │ Type │ Seq │ Status │ Payload │ -│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ -└────────┴────────┴────────┴────────┴─────────────┘ -``` - -## انواع پیام - -### 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) -``` - -## کدهای پاسخ - -| کد | نام | توضیح | -|----|-----|--------| -| 0x00 | OK | موفق | -| 0x01 | ERROR | خطای عمومی | -| 0x02 | AUTH_REQUIRED | نیاز به احراز هویت | -| 0x03 | INVALID_QUERY | خطای نحوی | -| 0x04 | NOT_FOUND | منبع یافت نشد | \ No newline at end of file diff --git a/docs/fa/api-http.md b/docs/fa/api-http.md deleted file mode 100644 index 94c8478..0000000 --- a/docs/fa/api-http.md +++ /dev/null @@ -1,62 +0,0 @@ -# HTTP/REST API - -API REST مبتنی بر JSON برای برنامه‌های وب. - -## Base URL - -``` -http://localhost:9470/api -``` - -## Endpoints - -### GET /api/users - -لیست همه کاربران: - -```bash -curl http://localhost:9470/api/users -``` - -### GET /api/users/:id - -دریافت کاربر با ID: - -```bash -curl http://localhost:9470/api/users/1 -``` - -### POST /api/users - -ایجاد کاربر: - -```bash -curl -X POST http://localhost:9470/api/users \ - -d '{"name": "Charlie", "age": 35}' -``` - -### PUT /api/users/:id - -به‌روزرسانی کاربر: - -```bash -curl -X PUT http://localhost:9470/api/users/1 \ - -d '{"name": "Alice", "age": 31}' -``` - -### DELETE /api/users/:id - -حذف کاربر: - -```bash -curl -X DELETE http://localhost:9470/api/users/1 -``` - -## Query Endpoint - -اجرای کوئری BaraQL: - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"sql": "SELECT * FROM users WHERE age > 18"}' -``` \ No newline at end of file diff --git a/docs/fa/api-websocket.md b/docs/fa/api-websocket.md deleted file mode 100644 index 340bc9c..0000000 --- a/docs/fa/api-websocket.md +++ /dev/null @@ -1,67 +0,0 @@ -# WebSocket API - -استریم تمام‌دوطرفه برای فیدهای داده real-time. - -## اتصال - -``` -ws://localhost:9471/ws -``` - -## مثال کلاینت - -```javascript -const ws = new WebSocket('ws://localhost:9471/ws'); - -ws.onopen = () => { - ws.send(JSON.stringify({ - type: 'query', - sql: 'SELECT * FROM users' - })); -}; - -ws.onmessage = (event) => { - console.log('Received:', JSON.parse(event.data)); -}; -``` - -## فرمت پیام - -```json -{ - "type": "query", - "id": "uuid", - "sql": "SELECT * FROM users" -} -``` - -## انواع پیام - -### درخواست - -```json -{ - "type": "query", - "id": "123", - "sql": "SELECT * FROM users" -} -``` - -### پاسخ - -```json -{ - "type": "result", - "id": "123", - "data": [{"id": 1, "name": "Alice"}] -} -``` - -### اشتراک - -```json -{ - "type": "subscribe", - "table": "users" -} -``` \ No newline at end of file diff --git a/docs/fa/architecture.md b/docs/fa/architecture.md deleted file mode 100644 index 47b3d08..0000000 --- a/docs/fa/architecture.md +++ /dev/null @@ -1,197 +0,0 @@ -# معماری BaraDB - -## بررسی اجمالی - -BaraDB یک **موتور پایگاه داده چند حالته** است که با Nim نوشته شده و ذخیره‌سازی سندی (KV)، گرافی، برداری، ستونی و جستجوی تمام‌متن را در یک موتور واحد با زبان پرس‌وجوی واحد **BaraQL** ترکیب می‌کند. - -## معماری لایه‌ای - -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. لایه کلاینت │ -│ پروتکل باینری │ HTTP/REST │ WebSocket │ توکار │ -├─────────────────────────────────────────────────────────┤ -│ 2. لایه پرس‌وجو (BaraQL) │ -│ لکسر → پارسر → AST → IR → بهینه‌ساز → کد‌ژن │ -├─────────────────────────────────────────────────────────┤ -│ 3. موتور اجرا │ -│ سند │ گراف │ بردار │ ستونی │ FTS │ -├─────────────────────────────────────────────────────────┤ -│ 4. ذخیره‌سازی │ -│ LSM-Tree │ B-Tree │ WAL │ Bloom │ فشردهسازی │ کش │ -├─────────────────────────────────────────────────────────┤ -│ 5. توزیع‌شده │ -│ Raft │ شاردینگ │ ریپلیکیشن │ Gossip │ -└─────────────────────────────────────────────────────────┘ -``` - -## لایه 1: لایه کلاینت - -چندین پروتکل ارتباطی: - -- **پروتکل باینری** (`protocol/wire.nim`): پروتکل باینری کارآمد big-endian با 16 نوع پیام -- **HTTP/REST** (`core/httpserver.nim`): API REST مبتنی بر JSON با چند نخی -- **WebSocket** (`core/websocket.nim`): استریم تمام‌دوطرفه -- **حالت توکار** (`storage/lsm.nim`): دسترسی مستقیم درون‌پروسه‌ای - -### مدیریت اتصال - -- **استخر اتصال** (`protocol/pool.nim`): محدودیت‌های کمینه/بیشینه اتصال با تایم‌اوت بیکاری -- **محدودیت نرخ** (`protocol/ratelimit.nim`): Token-bucket سراسری و برای هر کلاینت -- **احراز هویت** (`protocol/auth.nim`): JWT با HMAC-SHA256 و دسترسی مبتنی بر نقش -- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 با گواهینامه‌های خودتولید - -## لایه 2: لایه پرس‌وجو (BaraQL) - -خط لوله BaraQL: - -1. **لکسر** (`query/lexer.nim`): توکن‌سازی ورودی به بیش از 80 نوع توکن -2. **پارسر** (`query/parser.nim`): پارسر نزولی بازگشتی تولیدکننده AST -3. **AST** (`query/ast.nim`): بیش از 300 خط，覆盖 بیش از 25 نوع گره -4. **IR** (`query/ir.nim`): نمایش میانی برای نقشه‌های اجرا -5. **بهینه‌ساز** (`query/adaptive.nim`): بهینه‌سازی تطبیقی کross-modal -6. **کد‌ژن** (`query/codegen.nim`): ترجمه IR به عملیات ذخیره‌سازی -7. **اجراکننده** (`query/executor.nim`): اجرای نقشه‌ها با موازی‌سازی - -### برنامه‌ریزی کross-modal - -بهینه‌ساز (`query/adaptive.nim`) ترتیب اجرا را بین موتورها تعیین می‌کند: - -``` -1. تخمین گزینش‌پذیری برای هر شرط -2. ارسال گزینش‌پذیرترین شرط به موتور مربوطه اول -3. استفاده از فیلترهای Bloom برای جستجوهای KV -4. موازی‌سازی شاخه‌های مستقل -5. استریم نتایج برای اجتناب از مادی‌سازی -``` - -## لایه 3: موتور اجرا - -### موتور سند/KV -- **LSM-Tree** (`storage/lsm.nim`): ذخیره‌سازی بهینه برای نوشتن با MemTable، WAL، SSTables -- **اندیس B-Tree** (`storage/btree.nim`): اندیس مرتب برای اسکن بازه‌ای با COW - -### موتور برداری (`vector/`) -- **اندیس HNSW** (`vector/engine.nim`): گراف Navigable Small World سلسله‌مراتبی -- **اندیس IVF-PQ** (`vector/engine.nim`): فایل معکوس با کوانتیزاسیون محصول -- **عملیات SIMD** (`vector/simd.nim`): محاسبات فاصله بهینه‌شده با AVX2 -- **کوانتیزاسیون** (`vector/quant.nim`): اسکالر، محصول، و باینری - -### موتور گراف (`graph/`) -- **لیست مجاورت** (`graph/engine.nim`): گراف جهت‌دار با وزن یال -- **الگوریتم‌ها** (`graph/engine.nim`): BFS، DFS، Dijkstra، PageRank -- **تشخیص جامعه** (`graph/community.nim`): الگوریتم Louvain -- **تطبیق الگو** (`graph/community.nim`): ایزومورفیسم زیرگراف -- **پارسر Cypher** (`graph/cypher.nim`): پرس‌وجوهای گرافی Cypher-مانند - -### جستجوی تمام‌متن (`fts/`) -- **اندیس معکوس** (`fts/engine.nim`): اندیس سند-ترم -- **رتبه‌بندی** (`fts/engine.nim`): امتیازدهی BM25 و TF-IDF -- **جستجوی تقریبی** (`fts/engine.nim`): تطبیق با فاصله Levenshtein -- **چندزبانه** (`fts/multilang.nim`): توکنایزرهایی برای EN، BG، DE، FR، RU - -### موتور ستونی (`core/columnar.nim`) -- ذخیره‌سازی هر-ستونی برای پرس‌وجوهای تحلیلی -- کدگذاری RLE و دیکشنری -- تجمیع‌های شتاب‌گرفته با SIMD - -## لایه 4: ذخیره‌سازی - -- **LSM-Tree** (`storage/lsm.nim`): MemTable، WAL، SSTable، Bloom Filter، فشرده‌سازی -- **کش صفحه** (`storage/compaction.nim`): کش LRU با ردیابی نرخ hit -- **I/O نگاشته‌شده به حافظه** (`storage/mmap.nim`): دسترسی فایل مبتنی بر mmap -- **بازیابی** (`storage/recovery.nim`): بازپخش WAL و بازیابی پس از خرابی - -### مسیر نوشتن - -``` -کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن - → StorageOp → MVCC Txn → WAL Write → MemTable → Commit -``` - -### مسیر خواندن - -``` -کلاینت → پروتکل → احراز → پارسر → AST → IR → کد‌ژن - → StorageOp → MVCC Snapshot → MemTable → SSTable → Result -``` - -## لایه 5: توزیع‌شده - -- **Raft Consensus** (`core/raft.nim`): انتخاب رهبر، تکثیر لاگ -- **شاردینگ** (`core/sharding.nim`): Hash، range، و consistent hashing -- **ریپلیکیشن** (`core/replication.nim`): حالت‌های sync، async، semi-sync -- **پروتکل Gossip** (`core/gossip.nim`): مدیریت عضویت SWIM-مانند -- **تراکنش‌های توزیع‌شده** (`core/disttxn.nim`): commit دو مرحله‌ای - -## تصمیمات کلیدی طراحی - -1. **Nim خالص**: بدون وابستگی به Cython، Python یا Rust -2. **ذخیره‌سازی یکپارچه**: یک موتور برای KV، گراف، بردار، FTS و ستونی -3. **حالت توکار**: می‌تواند به‌عنوان کتابخانه یا سرور اجرا شود -4. **پروتکل باینری**: پروتکل سیمی کارآمد سفارشی -5. **MVCC**: کنترل همزمانی چندنسخه‌ای -6. **طرحواره-اول**: سیستم طرحواره با نوع قوی با وراثت -7. **کross-modal**: زبان پرس‌وجوی واحد در تمام مدل‌های داده -8. **تأیید رسمی**: الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و با TLC بررسی شده - -## آمار ماژول‌ها - -| دسته | ماژول‌ها | خطوط کد | هدف | -|------|----------|----------|-----| -| Core | 16 | ~4,200 | سرور، پروتکل‌ها، تراکنش‌ها، توزیع‌شده | -| Storage | 7 | ~3,100 | LSM، B-Tree، WAL، bloom، فشرده‌سازی، mmap | -| Query | 7 | ~2,800 | لکسر، پارسر، AST، IR، بهینه‌ساز، کد‌ژن، اجراکننده | -| Vector | 3 | ~1,200 | HNSW، IVF-PQ، کوانتیزاسیون، SIMD | -| Graph | 3 | ~1,000 | لیست مجاورت، الگوریتم‌ها، تشخیص جامعه | -| FTS | 2 | ~900 | اندیس معکوس، BM25، تقریبی، چندزبانه | -| Protocol | 7 | ~2,400 | Wire، HTTP، WebSocket، استخر، auth، محدودیت نرخ، SSL | -| Schema | 1 | ~600 | انواع، لینک‌ها، وراثت، مهاجرت‌ها | -| Client | 2 | ~800 | کلاینت باینری Nim، کمکی فایل | -| CLI | 1 | ~400 | شل تعاملی BaraQL | -| **مجموع** | **49** | **~14,100** | | - -## نمودارهای جریان داده - -### پرس‌وجوی ساده - -``` -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ -│ Client │───→│ Lexer │───→│ Parser │───→│ IR │───→│ Codegen│ -└────────┘ └────────┘ └────────┘ └────────┘ └───┬────┘ - │ -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ -│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘ -└────────┘ └────────┘ └────────┘ └────────┘ -``` - -### پرس‌وجوی کross-modal - -``` - ┌─────────────┐ - │ Parser │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Adaptive │ - │ Optimizer │ - └──────┬──────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ Vector │ │ Graph │ │ FTS │ - │ Engine │ │ Engine │ │ Engine │ - └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ - │ │ │ - └───────────────┼───────────────┘ - │ - ┌──────▼──────┐ - │ Join │ - │ & Sort │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Result │ - └─────────────┘ -``` \ No newline at end of file diff --git a/docs/fa/backup.md b/docs/fa/backup.md deleted file mode 100644 index 7093bc0..0000000 --- a/docs/fa/backup.md +++ /dev/null @@ -1,81 +0,0 @@ -# پشتیبان‌گیری و بازیابی - -## Snapshot آنلاین - -BaraDB از snapshot آنلاین بدون توقف سرور پشتیبانی می‌کند. - -### ایجاد snapshot - -```nim -import barabadb/core/backup - -var bm = newBackupManager() -bm.createSnapshot("/backup/baradb_2025-01-15") -``` - -### از طریق CLI - -```bash -./build/baradadb --snapshot --output=/backup/snapshot.db -``` - -### از طریق HTTP API - -```bash -curl -X POST http://localhost:9470/api/backup \ - -d '{"destination": "/backup/snapshot.db"}' -``` - -### پشتیبان‌گیری خودکار - -```bash -0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db -find /backup -name "baradb_*.db" -mtime +7 -delete -``` - -## بازیابی نقطه‌درزمان (PITR) - -### بازیابی از snapshot + WAL - -```bash -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal -``` - -### بازیابی از طریق SQL - -```sql -RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; -``` - -## سناریوهای بازیابی - -### سناریو 1: خرابی فایل - -```bash -cp /backup/sstables/000012.sst ./data/sstables/ -./build/baradadb --rebuild-index -``` - -### سناریو 2: از دست دادن کامل داده - -```bash -cp /backup/snapshot.db ./data/ -./build/baradadb --recover --wal-dir=/backup/wal -``` - -### سناریو 3: خرابی گره کلاستر - -```bash -BARADB_RAFT_NODE_ID=newnode \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## بهترین شیوه‌ها - -1. بازیابی را مرتب تست کنید -2. پشتیبان‌ها را خارج از سایت ذخیره کنید -3. پشتیبان‌ها را رمزنگاری کنید -4. کارهای پشتیبان‌گیری را مانیتور کنید \ No newline at end of file diff --git a/docs/fa/baraql.md b/docs/fa/baraql.md deleted file mode 100644 index 5f266e8..0000000 --- a/docs/fa/baraql.md +++ /dev/null @@ -1,597 +0,0 @@ -# مرجع زبان پرس‌وجو BaraQL - -BaraQL یک زبان پرس‌وجو سازگار با SQL با افزونه‌هایی برای عملیات گراف، بردار و سند است. - -## انواع داده - -| نوع | توضیح | مثال | -|------|--------|------| -| `null` | مقدار تهی | `null` | -| `bool` | بولی | `true`, `false` | -| `int8` | عدد صحیح 8 بیتی علامت‌دار | `127` | -| `int16` | عدد صحیح 16 بیتی علامت‌دار | `32767` | -| `int32` | عدد صحیح 32 بیتی علامت‌دار | `2147483647` | -| `int64` | عدد صحیح 64 بیتی علامت‌دار | `9223372036854775807` | -| `float32` | عدد اعشاری 32 بیتی | `3.14` | -| `float64` | عدد اعشاری 64 بیتی | `3.14159265359` | -| `str` | رشته UTF-8 | `'hello'` | -| `bytes` | بایت‌های خام | `0xDEADBEEF` | -| `array` | آرایه همگن | `[1, 2, 3]` | -| `vector` | بردار float32 | `[0.1, 0.2, 0.3]` | -| `object` | شیء کلید-مقدار | `{"a": 1}` | -| `datetime` | timestamp ISO 8601 | `'2025-01-15T10:30:00Z'` | -| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` | -| `json` | سند JSON | `{"key": "value"}` | -| `jsonb` | JSON باینری (تأیید‌شده) | `{"key": "value"}` | - -## پرس‌وجوهای پایه - -### SELECT - -```sql --- همه ستون‌ها -SELECT * FROM users; - --- ستون‌های خاص -SELECT name, age FROM users; - --- نام‌های مستعار -SELECT name AS full_name, age AS years FROM users; - --- DISTINCT -SELECT DISTINCT department FROM employees; - --- LIMIT و OFFSET -SELECT * FROM users LIMIT 10 OFFSET 20; -``` - -### WHERE - -```sql --- عملگرهای مقایسه‌ای -SELECT * FROM users WHERE age > 18; -SELECT * FROM users WHERE age >= 18 AND age <= 65; -SELECT * FROM users WHERE name = 'Alice'; -SELECT * FROM users WHERE name != 'Bob'; - --- بازه -SELECT * FROM users WHERE age BETWEEN 18 AND 65; - --- عضویت مجموعه -SELECT * FROM users WHERE department IN ('Engineering', 'Sales'); - --- تطبیق الگو -SELECT * FROM users WHERE name LIKE 'A%'; -SELECT * FROM users WHERE name ILIKE 'alice'; -- بدون حساسیت به حروف - --- بررسی NULL -SELECT * FROM users WHERE email IS NOT NULL; - --- عملگرهای منطقی -SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales'); -``` - -### ORDER BY - -```sql --- صعودی (پیش‌فرض) -SELECT * FROM users ORDER BY age; - --- نزولی -SELECT * FROM users ORDER BY age DESC; - --- چند ستون -SELECT * FROM users ORDER BY department ASC, age DESC; -``` - -### INSERT - -```sql --- یک ردیف -INSERT users { name := 'Alice', age := 30 }; - --- با نوع صریح -INSERT User { name := 'Alice', age := 30 }; - --- چند ردیف -INSERT users { - { name := 'Alice', age := 30 }, - { name := 'Bob', age := 25 } -}; -``` - -### UPDATE - -```sql --- به‌روزرسانی همه ردیف‌ها -UPDATE users SET status = 'active'; - --- به‌روزرسانی شرطی -UPDATE users SET age = 31 WHERE name = 'Alice'; - --- به‌روزرسانی چند ستون -UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice'; -``` - -### DELETE - -```sql --- حذف همه ردیف‌ها -DELETE FROM users; - --- حذف شرطی -DELETE FROM users WHERE age < 18; -``` - -## تجمیع و گروه‌بندی - -### توابع تجمیعی - -| تابع | توضیح | -|------|--------| -| `count(*)` | شمارش همه ردیف‌ها | -| `count(column)` | شمارش مقادیر غیر-NULL | -| `sum(column)` | مجموع مقادیر | -| `avg(column)` | میانگین | -| `min(column)` | کمینه | -| `max(column)` | بیشینه | -| `stddev(column)` | انحراف معیار | -| `variance(column)` | واریانس | - -### GROUP BY - -```sql -SELECT department, count(*) as emp_count, avg(salary) as avg_salary -FROM employees -GROUP BY department; - --- با HAVING -SELECT department, count(*) as emp_count -FROM employees -GROUP BY department -HAVING count(*) > 5; - --- گروه‌بندی چندگانه -SELECT department, role, count(*), avg(salary) -FROM employees -GROUP BY department, role; -``` - -## JOINها - -```sql --- INNER JOIN -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; - --- LEFT JOIN -SELECT u.name, o.total -FROM users u -LEFT JOIN orders o ON u.id = o.user_id; - --- RIGHT JOIN -SELECT u.name, o.total -FROM users u -RIGHT JOIN orders o ON u.id = o.user_id; - --- FULL JOIN -SELECT u.name, o.total -FROM users u -FULL JOIN orders o ON u.id = o.user_id; - --- CROSS JOIN -SELECT u.name, p.name -FROM users u -CROSS JOIN products p; - --- JOINهای چندگانه -SELECT u.name, o.id, p.name -FROM orders o -JOIN users u ON o.user_id = u.id -JOIN products p ON o.product_id = p.id; - --- Self JOIN -SELECT e.name, m.name as manager -FROM employees e -JOIN employees m ON e.manager_id = m.id; -``` - -## CTEها (عبارات جدول مشترک) - -```sql --- CTE واحد -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; - --- CTEهای چندگانه -WITH - recent AS ( - SELECT * FROM orders WHERE date > '2025-01-01' - ), - totals AS ( - SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id - ) -SELECT u.name, t.total -FROM users u -JOIN totals t ON u.id = t.user_id; - --- CTE بازگشتی -WITH RECURSIVE subordinates AS ( - SELECT id, name, manager_id FROM employees WHERE name = 'CEO' - UNION ALL - SELECT e.id, e.name, e.manager_id - FROM employees e - JOIN subordinates s ON e.manager_id = s.id -) -SELECT * FROM subordinates; -``` - -## زیرپرس‌وجوها - -```sql --- زیرپرس‌وجو در SELECT -SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count -FROM users u; - --- زیرپرس‌وجو در FROM -SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active; - --- زیرپرس‌وجو در WHERE (IN) -SELECT name FROM users WHERE id IN (SELECT user_id FROM orders); - --- زیرپرس‌وجو در WHERE (EXISTS) -SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id); - --- زیرپرس‌وجوی همبسته -SELECT name FROM users u -WHERE age > (SELECT avg(age) FROM users WHERE department = u.department); -``` - -## عبارات CASE - -```sql -SELECT name, - CASE - WHEN age < 13 THEN 'child' - WHEN age < 20 THEN 'teenager' - WHEN age < 65 THEN 'adult' - ELSE 'senior' - END AS category -FROM users; - --- CASE ساده -SELECT name, - CASE department - WHEN 'Engineering' THEN 'Tech' - WHEN 'Sales' THEN 'Revenue' - ELSE 'Other' - END AS division -FROM employees; -``` - -## عملیات مجموعه‌ای - -```sql --- UNION (متفاوت) -SELECT name FROM customers -UNION -SELECT name FROM suppliers; - --- UNION ALL (با تکرار) -SELECT name FROM customers -UNION ALL -SELECT name FROM suppliers; - --- INTERSECT -SELECT name FROM customers -INTERSECT -SELECT name FROM suppliers; - --- EXCEPT -SELECT name FROM customers -EXCEPT -SELECT name FROM suppliers; -``` - -## تعریف طرحواره - -### CREATE TYPE - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - --- با فیلدهای الزامی -CREATE TYPE User { - email: str REQUIRED, - name: str, - age: int32, - created_at: datetime DEFAULT now() -}; - --- با لینک‌ها -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; - --- با ویژگی‌های محاسباتی -CREATE TYPE Employee { - name: str, - base_salary: float64, - bonus: float64, - total_compensation: float64 COMPUTED (base_salary + bonus) -}; -``` - -### وراثت - -```sql -CREATE TYPE Animal { - name: str -}; - -CREATE TYPE Dog EXTENDING Animal { - breed: str -}; - -CREATE TYPE Cat EXTENDING Animal { - indoor: bool -}; -``` - -### اندیس‌ها - -```sql -CREATE INDEX idx_users_name ON users(name); -CREATE UNIQUE INDEX idx_users_email ON users(email); -CREATE INDEX idx_users_age ON users(age) USING btree; -``` - -### DROP - -```sql -DROP TYPE User; -DROP INDEX idx_users_name; -``` - -## جستجوی برداری - -```sql --- درج با بردار -INSERT articles { - title := 'Nim Programming', - embedding := [0.1, 0.2, 0.3, 0.4] -}; - --- جستجوی شباهت (فاصله کسینوسی) -SELECT title FROM articles -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- فاصله اقلیدسی -SELECT title FROM articles -ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- ضرب نقطه‌ای -SELECT title FROM articles -ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC -LIMIT 5; - --- با فیلتر ابرداده -SELECT title FROM articles -WHERE category = 'tech' -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; -``` - -## الگوهای گراف - -```sql --- یافتن دوستان Alice -MATCH (p:Person)-[:KNOWS]->(friend:Person) -WHERE p.name = 'Alice' -RETURN friend.name; - --- یافتن کوتاه‌ترین مسیر -MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person)) -WHERE a.name = 'Alice' AND b.name = 'Bob' -RETURN path; - --- یافتن همه روابط -MATCH (p:Person)-[r]->(other) -WHERE p.name = 'Alice' -RETURN type(r), other.name; - --- جهش‌های چندگانه -MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) -WHERE a.name = 'Alice' -RETURN c.name; - --- با تجمیع‌ها -MATCH (p:Person)-[:KNOWS]->(friend) -RETURN p.name, count(friend) as friend_count -ORDER BY friend_count DESC; -``` - -## جستجوی تمام‌متن - -```sql --- جستجوی پایه -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('database programming'); - --- با امتیاز ارتباط -SELECT title, relevance() -FROM articles -WHERE MATCH(title, body) AGAINST('Nim language') -ORDER BY relevance() DESC; - --- حالت بولی -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE); - --- جستجوی تقریبی -SELECT * FROM articles -WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2); -``` - -## تراکنش‌ها - -```sql -BEGIN; -INSERT users { name := 'Alice', age := 30 }; -INSERT orders { user_id := last_insert_id(), total := 100 }; -COMMIT; - --- با savepoint -BEGIN; -INSERT users { name := 'Bob', age := 25 }; -SAVEPOINT sp1; -INSERT orders { user_id := last_insert_id(), total := 200 }; --- اوپس، برگشت به savepoint -ROLLBACK TO sp1; -COMMIT; -``` - -## توابع تعریف‌شده کاربر - -```sql --- ثبت یک UDF -CREATE FUNCTION greet(name str) -> str { - RETURN 'Hello, ' || name || '!'; -}; - --- استفاده -SELECT greet(name) FROM users; - --- توابع داخلی -SELECT abs(-5), sqrt(16), lower('HELLO'), len('test'); -``` - -## اشاره‌های پرس‌وجو - -```sql --- اجبار استفاده از اندیس -SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18; - --- اجبار جستجوی برداری تقریبی -SELECT /*+ APPROXIMATE */ * FROM vectors -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; - --- اجرای موازی -SELECT /*+ PARALLEL(4) */ * FROM large_table; -``` - -## توابع پنجره‌ای - -```sql --- توابع رتبه‌بندی -SELECT - name, - department, - ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn, - RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r, - DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr -FROM employees; - --- توابع مقدار -SELECT - name, - salary, - LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary, - LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary, - FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest, - LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive -FROM employees; - --- توابع توزیع -SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees; -``` - -### مشخصات فریم - -```sql --- فریم ROWS -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - ROWS BETWEEN 1 PRECEDING AND CURRENT ROW -) - --- فریم RANGE -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW -) -``` - -## ERP چند مستأجری - -BaraDB از اجرای چندین شرکت (tenant) در یک نمونه پایگاه داده پشتیبانی می‌کند، با استفاده از **امنیت سطح سطر (RLS)** همراه با **متغیرهای جلسه**. - -### متغیرهای جلسه - -```sql -SET app.tenant_id = 'company-123'; -SELECT current_setting('app.tenant_id') AS tenant; -``` - -### کاربر / نقش فعلی - -```sql -SELECT current_user AS me, current_role AS my_role; -``` - -### جداسازی مستأجر با RLS - -```sql --- فعال کردن RLS روی جدول -ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; - --- ایجاد سیاست فیلترینگ بر اساس مستأجر -CREATE POLICY tenant_isolation ON invoices - FOR SELECT USING (tenant_id = current_setting('app.tenant_id')); - --- هر جلسه فقط داده‌های خود را می‌بیند -SET app.tenant_id = 'company-a'; -SELECT * FROM invoices; -- فقط ردیف‌های company-a -``` - -### چرا چند مستأجری؟ - -- **یک نمونه، مستأجران زیاد** — نیازی به اجرای ۱۰۰ پایگاه داده جداگانه نیست -- **اسناد JSONB** — ذخیره‌سازی با طرح انعطاف‌پذیر، افزودن آسان فیلدها برای هر مستأجر -- **RLS تضمین می‌کند** — پایگاه داده مرزهای مستأجر را اعمال می‌کند، نه فقط برنامه - -## کلمات کلیدی پشتیبانی‌شده - -| دسته | کلمات کلیدی | -|----------|----------| -| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT | -| DML | INSERT, UPDATE, DELETE, SET, VALUES | -| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE | -| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON | -| Set | UNION, UNION ALL, INTERSECT, EXCEPT | -| CTEs | WITH, RECURSIVE, AS | -| Case | CASE, WHEN, THEN, ELSE, END | -| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT | -| Graph | MATCH, RETURN, WHERE, shortestPath, type | -| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS | -| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> | -| JSON | ->, ->> | -| FTS | @@ (BM25 match) | -| Recovery | RECOVER TO TIMESTAMP | -| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting | -| Session | SET, current_setting, current_user, current_role | -| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING | -| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE | \ No newline at end of file diff --git a/docs/fa/btree.md b/docs/fa/btree.md deleted file mode 100644 index af6bc22..0000000 --- a/docs/fa/btree.md +++ /dev/null @@ -1,25 +0,0 @@ -# اندیس B-Tree - -ساختار اندیس مرتب برای اسکن بازه‌ای و جستجوی نقطه‌ای. - -## استفاده - -```nim -import barabadb/storage/btree - -var btree = newBTreeIndex[string, string]() - -btree.insert("key1", "value1") -btree.insert("key2", "value2") - -let values = btree.get("key1") -let range = btree.scan("key_a", "key_z") -btree.delete("key1") -``` - -## ویژگی‌ها - -- ذخیره‌سازی مرتب کلید-مقدار -- جستجوهای بازه‌ای (BETWEEN, >, <, >=, <=) -- اسکن پیشوندی -- پشتیبانی از iterator \ No newline at end of file diff --git a/docs/fa/changelog.md b/docs/fa/changelog.md deleted file mode 100644 index 1e055b4..0000000 --- a/docs/fa/changelog.md +++ /dev/null @@ -1,70 +0,0 @@ -# سیاهه تغییرات - -## [0.1.0] — 2025-01-15 - -### افزوده شده - -- **موتورهای ذخیره‌سازی اصلی** - - LSM-Tree با MemTable، WAL، SSTables و size-tiered compaction - - B-Tree اندیس مرتب با اسکن بازه‌ای و MVCC copy-on-write - - Bloom filterها - - Memory-mapped I/O - - LRU page cache - -- **موتور کوئری (BaraQL)** - - لکسر SQL-سازگار با 80+ نوع توکن - - پارسر تولیدکننده AST با 25+ نوع گره - - نمایش میانی (IR) - - بهینه‌ساز تطبیقی - - اجراکننده موازی - -- **قابلیت‌های زبان BaraQL** - - SELECT, INSERT, UPDATE, DELETE - - WHERE, ORDER BY, LIMIT, OFFSET - - GROUP BY, HAVING - - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN - - CTEs با WITH - - زیرکوئری‌ها - - CASE - - UNION, INTERSECT, EXCEPT - -- **موتور برداری** - - اندیس HNSW - - IVF-PQ - - SIMD-بهینه‌شده - -- **موتور گراف** - - لیست مجاورت - - BFS و DFS - - Dijkstra - - PageRank - - Louvain - - Cypher - -- **جستجوی تمام‌متن** - - اندیس معکوس - - BM25 - - TF-IDF - - جستجوی فازی - - چندزبانه - -- **پروتکل‌ها** - - Binary wire protocol - - HTTP/REST JSON API - - WebSocket - - Connection pooling - - JWT auth - - TLS/SSL - -- **سیستم توزیع‌شده** - - Raft consensus - - Sharding - - Replication - - Gossip - - Two-phase commit - -### عملکرد - -- LSM-Tree: 580K نوشتن/ثانیه، 720K خواندن/ثانیه -- B-Tree: 1.2M درج/ثانیه -- Vector SIMD: 850K فاصله کسینوسی/ثانیه \ No newline at end of file diff --git a/docs/fa/clients.md b/docs/fa/clients.md deleted file mode 100644 index dac3ac2..0000000 --- a/docs/fa/clients.md +++ /dev/null @@ -1,66 +0,0 @@ -# SDK های کلاینت - -BaraDB کتابخانه‌های کلاینت رسمی برای JavaScript/TypeScript، Python، Nim و Rust فراهم می‌کند. - -## JavaScript / TypeScript - -### نصب - -```bash -npm install baradb -``` - -### استفاده پایه - -```typescript -import { Client } from 'baradb'; - -const client = new Client('localhost', 9472); -await client.connect(); - -const result = await client.query('SELECT name, age FROM users WHERE age > 18'); -``` - -## Python - -### نصب - -```bash -pip install baradb -``` - -### استفاده پایه - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -result = client.query("SELECT name, age FROM users WHERE age > 18") -``` - -## Nim (حالت توکار) - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## Rust - -```rust -use baradb::Client; - -let mut client = Client::connect("localhost:9472").await?; -``` - -## HTTP/REST - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` \ No newline at end of file diff --git a/docs/fa/columnar.md b/docs/fa/columnar.md deleted file mode 100644 index ec67458..0000000 --- a/docs/fa/columnar.md +++ /dev/null @@ -1,50 +0,0 @@ -# ذخیره‌سازی ستونی - -ذخیره‌سازی ستون-محور برای کوئری‌های تحلیلی و تجمیع‌ها. - -## استفاده - -```nim -import barabadb/core/columnar - -var batch = newColumnBatch() -var ageCol = batch.addInt64Col("age") -var nameCol = batch.addStringCol("name") - -ageCol.appendInt64(25) -nameCol.appendString("Alice") -``` - -## تجمیع‌ها - -```nim -echo ageCol.sumInt64() -echo ageCol.avgInt64() -echo ageCol.minInt64() -echo ageCol.maxInt64() -``` - -## کدگذاری - -### RLE - -```nim -let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) -``` - -### Dictionary - -```nim -let dict = dictEncode(@["apple", "banana", "apple"]) -``` - -## انواع ستون - -| نوع | توضیح | -|-----|--------| -| `int32` | عدد صحیح 32 بیتی | -| `int64` | عدد صحیح 64 بیتی | -| `float32` | عدد اعشاری 32 بیتی | -| `float64` | عدد اعشاری 64 بیتی | -| `string` | رشته با طول متغیر | -| `bool` | بولی | \ No newline at end of file diff --git a/docs/fa/configuration.md b/docs/fa/configuration.md deleted file mode 100644 index f3488c2..0000000 --- a/docs/fa/configuration.md +++ /dev/null @@ -1,94 +0,0 @@ -# مرجع پیکربندی - -BaraDB از **متغیرهای محیطی**، **فایل پیکربندی** یا **پرچم‌های خط فرمان** پیکربندی می‌شود. - -## اولویت - -1. پرچم‌های خط فرمان (بالاترین) -2. متغیرهای محیطی -3. فایل پیکربندی (`baradb.conf` یا `baradb.json`) -4. مقادیر پیش‌فرض (پایین‌ترین) - -## متغیرهای محیطی - -### شبکه - -| متغیر | پیش‌فرض | توضیح | -|--------|---------|--------| -| `BARADB_ADDRESS` | `127.0.0.1` | آدرس اتصال | -| `BARADB_PORT` | `9472` | پورت پروتکل باینری | -| `BARADB_HTTP_PORT` | `9470` | پورت HTTP/REST API | -| `BARADB_WS_PORT` | `9471` | پورت WebSocket | - -### ذخیره‌سازی - -| متغیر | پیش‌فرض | توضیح | -|--------|---------|--------| -| `BARADB_DATA_DIR` | `./data` | مسیر پوشه داده | -| `BARADB_MEMTABLE_SIZE_MB` | `64` | اندازه MemTable (MB) | -| `BARADB_CACHE_SIZE_MB` | `256` | اندازه کش صفحه (MB) | - -### TLS/SSL - -| متغیر | پیش‌فرض | توضیح | -|--------|---------|--------| -| `BARADB_TLS_ENABLED` | `false` | فعال‌سازی TLS | -| `BARADB_CERT_FILE` | — | مسیر گواهی TLS | -| `BARADB_KEY_FILE` | — | مسیر کلید TLS | - -### امنیت - -| متغیر | پیش‌فرض | توضیح | -|--------|---------|--------| -| `BARADB_AUTH_ENABLED` | `false` | فعال‌سازی احراز هویت | -| `BARADB_JWT_SECRET` | — | رمز امضای JWT | - -## فایل پیکربندی - -### baradb.conf - -```ini -[server] -address = "0.0.0.0" -port = 9472 -http_port = 9470 - -[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" - -[auth] -enabled = true -jwt_secret = "change-me-in-production" -``` - -## پرچم‌های خط فرمان - -```bash -./build/baradadb --help -``` - -## نمونه پیکربندی‌ها - -### توسعه - -```bash -./build/baradadb --log-level debug --data-dir ./dev_data -``` - -### تولید - گره واحد - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -BARADB_MEMTABLE_SIZE_MB=256 \ -BARADB_CACHE_SIZE_MB=1024 \ -./build/baradadb -``` \ No newline at end of file diff --git a/docs/fa/crossmodal.md b/docs/fa/crossmodal.md deleted file mode 100644 index 20dfd43..0000000 --- a/docs/fa/crossmodal.md +++ /dev/null @@ -1,40 +0,0 @@ -# پرس‌وجوهای بین‌حالتی - -توانایی منحصربه‌فرد BaraDB برای اجرای کوئری‌هایی که چندین موتور ذخیره‌سازی را در یک عبارت BaraQL واحد پوشش می‌دهند. - -## نمای کلی - -- **سند/KV** (LSM-Tree) — رکوردهای ساختاریافته -- **گراف** (لیست مجاورت) — روابط -- **بردار** (HNSW/IVF-PQ) — جستجوی شباهت -- **تمام‌متن** (اندیس معکوس) — جستجوی متنی -- **ستونی** — تجمیع‌های تحلیلی - -## پترن‌های کوئری - -### بردار + تمام‌متن - -```sql -SELECT title FROM articles -WHERE MATCH(body) AGAINST('machine learning') -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; -``` - -### گراف + بردار - -```sql -MATCH (u:User)-[:KNOWS]->(friend:User) -WHERE u.name = 'Alice' -ORDER BY cosine_distance(friend.taste_vector, u.taste_vector) -RETURN friend.name; -``` - -## بهینه‌سازی - -### برنامه‌ریز پرس‌وجو - -1. فیلتر انتخابی‌ترین اول -2. پوش‌داون پریدایکت‌ها به هر موتور -3. فیلترهای Bloom برای جستجوهای KV -4. موازی‌سازی شاخه‌های مستقل \ No newline at end of file diff --git a/docs/fa/deployment.md b/docs/fa/deployment.md deleted file mode 100644 index d549545..0000000 --- a/docs/fa/deployment.md +++ /dev/null @@ -1,249 +0,0 @@ -# راهنمای استقرار BaraDB - -## Docker - -برای راهنمای کامل استقرار Docker به [راهنمای Docker](docker.md) مراجعه کنید. - -### شروع سریع - -```bash -docker build -t baradb:latest . -docker compose up -d -``` - -### فایل‌های Docker Compose - -| فایل | کاربرد | -|------|--------| -| `docker-compose.yml` | توسعه | -| `docker-compose.prod.yml` | تولید | -| `docker-compose.override.yml` | Override توسعه (خودکار) | - -### تولید - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -### Docker Swarm - -```bash -docker stack deploy -c docker-compose.prod.yml baradb -``` - -## سرویس systemd - -فایل `/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 - -# Hardening امنیت -NoNewPrivileges=true -ProtectSystem=strict -ProtectHome=true -ReadWritePaths=/var/lib/baradb/data -ProtectKernelTunables=true -ProtectKernelModules=true -ProtectControlGroups=true - -[Install] -WantedBy=multi-user.target -``` - -فعال‌سازی و شروع: - -```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"; - } -} -``` - -## دسترس‌پذیری بالا - -### خوشه Raft سه گره‌ای - -```bash -# گره 1 -BARADB_RAFT_NODE_ID=node1 \ -BARADB_RAFT_PEERS=node2:9001,node3:9001 \ -./build/baradadb - -# گره 2 -BARADB_RAFT_NODE_ID=node2 \ -BARADB_RAFT_PEERS=node1:9001,node3:9001 \ -./build/baradadb - -# گره 3 -BARADB_RAFT_NODE_ID=node3 \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## استقرار ابری - -### AWS EC2 - -نمونه توصیه‌شده: `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 (فقط HTTP) - -```bash -gcloud run deploy baradb \ - --image gcr.io/PROJECT/baradb \ - --port 9470 \ - --memory 4Gi \ - --cpu 2 \ - --max-instances 10 -``` \ No newline at end of file diff --git a/docs/fa/distributed.md b/docs/fa/distributed.md deleted file mode 100644 index 254589f..0000000 --- a/docs/fa/distributed.md +++ /dev/null @@ -1,82 +0,0 @@ -# سیستم‌های توزیع‌شده - -BaraDB از استقرار توزیع‌شده با اجماع Raft، شاردینگ و تکثیر پشتیبانی می‌کند. - -## اجماع Raft - -انتخاب رهبر و تکثیر لاگ: - -```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() -``` - -## شاردینگ - -```nim -import barabadb/core/sharding - -var router = newShardRouter(ShardConfig( - numShards: 4, - replicas: 2, - strategy: ssHash -)) -``` - -### استراتژی‌های شاردینگ - -| استراتژی | توضیح | -|-----------|--------| -| `ssHash` | شاردینگ مبتنی بر hash | -| `ssRange` | شاردینگ مبتنی بر بازه | -| `ssConsistent` | هش سازگار | - -## تکثیر - -```nim -import barabadb/core/replication - -var rm = newReplicationManager(rmSync) -rm.addReplica(newReplica("r1", "10.0.0.1", 9472)) -``` - -### حالت‌های تکثیر - -| حالت | توضیح | -|------|--------| -| `rmSync` | تکثیر همگام | -| `rmAsync` | تکثیر ناهمگام | -| `rmSemiSync` | تکثیر نیمه‌همگام | - -## پروتکل Gossip - -```nim -import barabadb/core/gossip - -var g = newGossipManager() -g.addNode("node1") -g.addNode("node2") -g.tick() -``` - -## تراکنش‌های توزیع‌شده - -```nim -import barabadb/core/disttxn - -var dt = newDistributedTxn() -dt.prepare(@["node1", "node2"]) -dt.commit() -``` - -## تأیید رسمی - -الگوریتم‌های اصلی توزیع‌شده در TLA+ مشخص و تأیید شده‌اند. \ No newline at end of file diff --git a/docs/fa/docker.md b/docs/fa/docker.md deleted file mode 100644 index 2f38bb9..0000000 --- a/docs/fa/docker.md +++ /dev/null @@ -1,113 +0,0 @@ -# راهنمای استقرار Docker - -## شروع سریع - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB - -docker build -t baradb:latest . - -docker compose up -d - -docker compose ps -docker compose logs -f -``` - -## فایل‌ها - -| فایل | توضیح | -|------|--------| -| `Dockerfile` | ساخت multi-stage production | -| `docker-compose.yml` | پیکربندی توسعه | -| `docker-compose.prod.yml` | پیکربندی تولید | -| `docker-compose.override.yml` | Override توسعه | -| `docker-entrypoint.sh` | اسکریپت entrypoint | -| `.dockerignore` | فایل‌های مستثنی از کپی | -| `scripts/docker-build.sh` | اسکریپت کمکی ساخت | -| `scripts/docker-run.sh` | اسکریپت کمکی اجرا | - -## ساخت تصویر - -```bash -docker build -t baradb:latest . -./scripts/docker-build.sh -``` - -## اجرا - -### توسعه - -```bash -docker compose up -d -docker compose down -docker compose logs -f -``` - -### تولید - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -### دستی - -```bash -docker run -d \ - --name baradb \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - baradb:latest -``` - -## پورت‌ها - -| پورت | توضیح | -|------|--------| -| `9472` | پروتکل باینری | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## متغیرهای محیطی - -| متغیر | پیش‌فرض | توضیح | -|--------|---------|--------| -| `BARADB_ADDRESS` | `0.0.0.0` | آدرس اتصال | -| `BARADB_PORT` | `9472` | پورت پروتکل باینری | -| `BARADB_HTTP_PORT` | `9470` | پورت HTTP | -| `BARADB_DATA_DIR` | `/data` | پوشه داده | - -## Volumeها - -| مسیر | توضیح | -|------|--------| -| `/data` | پوشه اصلی داده | -| `/data/server/wal` | Write-ahead log | -| `/data/server/sstables` | فایل‌های SSTable | - -## چک‌لیست تولید - -- [ ] ایجاد گواهی‌های TLS -- [ ] تنظیم `BARADB_JWT_SECRET` قوی -- [ ] پیکربندی قوانین فایروال -- [ ] تنظیم پشتیبان‌گیری منظم -- [ ] بررسی محدودیت منابع -- [ ] تنظیم مانیتورینگ - -## TLS در Docker - -```bash -mkdir -p certs -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout certs/server.key -out certs/server.crt -``` - -## پشتیبان‌گیری - -```bash -docker exec baradb /app/backup backup --data-dir=/data -docker exec baradb /app/backup list -docker exec baradb /app/backup restore --input=backup_xxx.tar.gz -``` \ No newline at end of file diff --git a/docs/fa/fts.md b/docs/fa/fts.md deleted file mode 100644 index cbbe755..0000000 --- a/docs/fa/fts.md +++ /dev/null @@ -1,47 +0,0 @@ -# موتور جستجوی تمام‌متن - -اندیس معکوس با رتبه‌بندی BM25 و TF-IDF. - -## استفاده - -```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") - -let results = idx.search("programming language") -let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) -``` - -## روش‌های رتبه‌بندی - -### BM25 - -```nim -let bm25 = idx.searchBM25("query terms") -``` - -### TF-IDF - -```nim -let tfidf = idx.searchTfidf("query terms") -``` - -## ویژگی‌های جستجو - -| ویژگی | توضیح | -|--------|--------| -| Fuzzy search | تساهل فاصله Levenshtein | -| Wildcard | پیشوند، پسوند، میانوند | -| Regex | الگوهای regular | -| Phrase search | تطبیق عبارت دقیق | -| Boolean | عملگرهای AND, OR, NOT | - -## رابط SQL - -```sql -CREATE INDEX idx_fts ON articles(body) USING FTS; -SELECT * FROM articles WHERE body @@ 'machine learning'; -``` \ No newline at end of file diff --git a/docs/fa/graph.md b/docs/fa/graph.md deleted file mode 100644 index 25a650f..0000000 --- a/docs/fa/graph.md +++ /dev/null @@ -1,42 +0,0 @@ -# موتور گراف - -ذخیره‌سازی لیست مجاورت با الگوریتم‌های داخلی برای پیمایش و تحلیل گراف. - -## استفاده - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -``` - -## الگوریتم‌ها - -| الگوریتم | توضیح | -|----------|--------| -| `bfs` | پیمایش اول سطح | -| `dfs` | پیمایش اول عمق | -| `dijkstra` | کوتاه‌ترین مسیر وزن‌دار | -| `pageRank` | رتبه‌بندی اهمیت گره | -| `louvain` | تشخیص جامعه | -| `patternMatch` | ایزومورفیسم زیرگراف | - -## Cypher - -```nim -import barabadb/graph/cypher - -var engine = newCypherEngine(g) -let results = engine.execute(""" - MATCH (p:Person)-[:KNOWS]->(friend:Person) - WHERE p.name = 'Alice' - RETURN friend.name -""") -``` \ No newline at end of file diff --git a/docs/fa/index.md b/docs/fa/index.md deleted file mode 100644 index 0ab1e17..0000000 --- a/docs/fa/index.md +++ /dev/null @@ -1,59 +0,0 @@ -# مستندات BaraDB (فارسی) - -**یک موتور پایگاه داده چند حالته به زبان Nim — کاملاً بومی، بدون وابستگی.** - -## پیوندهای سریع - -> **توجه:** مستندات فارسی در حال توسعه است. لطفاً برای اطلاعات کامل به [نسخه انگلیسی](../en/) مراجعه کنید. - -### شروع کار -- [نصب](../en/installation.md) -- [شروع سریع](../en/quickstart.md) -- [بررسی معماری](../en/architecture.md) -- [پیکربندی](../en/configuration.md) -- [راهنمای استقرار](../en/deployment.md) - -### مفاهیم اصلی -- [BaraQL — زبان پرس‌وجو](../en/baraql.md) -- [موتورهای ذخیره‌سازی](../en/storage.md) -- [سیستم طرحواره](../en/schema.md) -- [پرس‌وجوهای بین‌حالتی](../en/crossmodal.md) - -### موتورها -- [LSM-Tree](../en/lsm.md) -- [اندیس B-Tree](../en/btree.md) -- [جستجوی برداری](../en/vector.md) -- [موتور گراف](../en/graph.md) -- [جستجوی تمام‌متن](../en/fts.md) -- [ذخیره‌سازی ستونی](../en/columnar.md) - -### API و کلاینت‌ها -- [SDK های کلاینت](../en/clients.md) -- [پروتکل باینری](../en/api-binary.md) -- [HTTP/REST API](../en/api-http.md) -- [WebSocket API](../en/api-websocket.md) -- [مرجع پروتکل](../en/protocol.md) - -### عملیات -- [عملکرد و معیارسنجی](../en/performance.md) -- [امنیت](../en/security.md) -- [نظارت](../en/monitoring.md) -- [پشتیبان‌گیری و بازیابی](../en/backup.md) -- [عیب‌یابی](../en/troubleshooting.md) - -### مباحث پیشرفته -- [تراکنش‌ها و MVCC](../en/transactions.md) -- [سیستم‌های توزیع‌شده](../en/distributed.md) -- [توابع تعریف‌شده کاربر](../en/udf.md) - ---- - -## اطلاعات پروژه - -- [تاریخچه تغییرات](../en/changelog.md) -- [مجوز](../../LICENSE) -- [مخزن GitHub](https://github.com/katehonz/barabaDB) - ---- - -*مستندات فارسی در دست تهیه است.* \ No newline at end of file diff --git a/docs/fa/installation.md b/docs/fa/installation.md deleted file mode 100644 index 9eee320..0000000 --- a/docs/fa/installation.md +++ /dev/null @@ -1,309 +0,0 @@ -# راهنمای نصب BaraDB - -## الزامات - -- **کامپایلر Nim** >= 2.2.0 -- **فایل‌های هدر OpenSSL** (برای پشتیبانی TLS) -- **سیستم‌عامل**: لینوکس، macOS، ویندوز - -### پلتفرم‌های پشتیبانی‌شده - -| سیستم‌عامل | معماری | وضعیت | -|------------|--------|--------| -| لینوکس | x86_64 | ✅ پشتیبانی کامل | -| لینوکس | ARM64 | ✅ پشتیبانی کامل | -| macOS | x86_64 | ✅ پشتیبانی کامل | -| macOS | ARM64 (Apple Silicon) | ✅ پشتیبانی کامل | -| ویندوز | x86_64 | ✅ پشتیبانی‌شده | -| FreeBSD | x86_64 | 🟡 تست‌شده توسط جامعه | - -## نصب Nim - -### لینوکس - -```bash -# نصب‌کننده رسمی -curl https://nim-lang.org/choosenim/init.sh -sSf | sh - -# Ubuntu/Debian -sudo apt-get update -sudo apt-get install nim - -# Fedora -sudo dnf install nim - -# Arch Linux -sudo pacman -S nim -``` - -### macOS - -```bash -# Homebrew -brew install nim - -# MacPorts -sudo port install nim -``` - -### ویندوز - -```powershell -# Using choosenim -curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell - - -# Using winget -winget install nim - -# Using scoop -scoop install nim -``` - -### تأیید نصب - -```bash -nim --version -# انتظار: Nim Compiler Version 2.2.0 یا بالاتر -``` - -## نصب OpenSSL - -### لینوکس - -```bash -# Ubuntu/Debian -sudo apt-get install libssl-dev - -# Fedora -sudo dnf install openssl-devel - -# Arch Linux -sudo pacman -S openssl -``` - -### macOS - -OpenSSL همراه سیستم است. در صورت نیاز: - -```bash -brew install openssl -``` - -### ویندوز - -OpenSSL همراه توزیع ویندوز Nim است. برای ساخت دستی، -از [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) دانلود کنید. - -## ساخت BaraDB - -### کلون کردن مخزن - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB -``` - -### نصب وابستگی‌ها - -```bash -nimble install -d -y -``` - -### گزینه‌های ساخت - -#### ساخت دیباگ - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -#### ساخت ریلیز (توصیه‌شده) - -```bash -nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim -``` - -#### استفاده از Nimble Tasks - -```bash -# ساخت دیباگ -nimble build_debug - -# ساخت ریلیز -nimble build_release -``` - -#### کاهش حجم باینری - -```bash -nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim -strip build/baradadb -``` - -### تأیید ساخت - -```bash -./build/baradadb --version -# انتظار: BaraDB v1.1.6 — Multimodal Database Engine -``` - -## اجرای تست‌ها - -### همه تست‌ها - -```bash -nim c -d:ssl -r tests/test_all.nim -``` - -### مجموعه‌های تست خاص - -```bash -# تست‌های ذخیره‌سازی -nim c -d:ssl -r tests/test_storage.nim - -# تست‌های موتور پرس‌وجو -nim c -d:ssl -r tests/test_query.nim - -# تست‌های پروتکل -nim c -d:ssl -r tests/test_protocol.nim -``` - -### بنچمارک‌ها - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## گزینه‌های نصب - -### نصب سیستمی - -```bash -# ساخت باینری ریلیز -nimble build_release - -# نصب در /usr/local/bin -sudo cp build/baradadb /usr/local/bin/ -sudo chmod +x /usr/local/bin/baradadb - -# ایجاد پوشه داده -sudo mkdir -p /var/lib/baradb -sudo chmod 755 /var/lib/baradb -``` - -### باینری از پیش ساخته‌شده - -آخرین ریلیز را برای پلتفرم خود دانلود کنید: - -```bash -# لینوکس x86_64 -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 - -# لینوکس ARM64 -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64 -chmod +x baradadb-linux-arm64 -mv baradadb-linux-arm64 /usr/local/bin/baradadb - -# macOS -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64 -chmod +x baradadb-darwin-amd64 -mv baradadb-darwin-amd64 /usr/local/bin/baradadb -``` - -### Docker - -```bash -# دریافت ایمیج رسمی -docker pull barabadb/barabadb:latest - -# اجرا -docker run -d \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - barabadb/barabadb -``` - -### Docker Compose - -```bash -docker-compose up -d -``` - -### استفاده توکار (پروژه‌های Nim) - -به فایل `.nimble` خود اضافه کنید: - -```nim -requires "barabadb >= 0.1.0" -``` - -در کد خود استفاده کنید: - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## اجرای اولیه - -```bash -# شروع سرور -./build/baradadb - -# خروجی مورد انتظار: -# BaraDB v1.1.6 — Multimodal Database Engine -# BaraDB TCP listening on 127.0.0.1:9472 - -# تست با HTTP API -curl http://localhost:9470/health - -# شل تعاملی -./build/baradadb --shell -``` - -## عیب‌یابی نصب - -### "cannot open file: hunos" - -```bash -nimble install -d -y -``` - -### "BaraDB requires SSL support" - -همیشه با `-d:ssl` کامپایل کنید: - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -### کامپایل کند - -از کامپایل موازی استفاده کنید: - -```bash -nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim -``` - -### حجم باینری زیاد - -از بهینه‌سازی اندازه استفاده کنید: - -```bash -nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim -``` - -## مراحل بعدی - -- [راهنمای شروع سریع](quickstart.md) -- [مرجع پیکربندی](configuration.md) -- [بررسی معماری](architecture.md) -- [زبان پرس‌وجو BaraQL](baraql.md) \ No newline at end of file diff --git a/docs/fa/lsm.md b/docs/fa/lsm.md deleted file mode 100644 index cf4c097..0000000 --- a/docs/fa/lsm.md +++ /dev/null @@ -1,48 +0,0 @@ -# موتور ذخیره‌سازی LSM-Tree - -موتور ذخیره‌سازی اصلی BaraDB با معماری Log-Structured Merge-Tree. - -## معماری - -``` -┌─────────────────────────────────────────────┐ -│ Writes │ -│ (append to WAL + MemTable) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ MemTable │ -│ (in-memory sorted buffer) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ SSTable │ -│ (sorted string table on disk) │ -└─────────────────────────────────────────────┘ -``` - -## استفاده - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") - -db.put("key1", cast[seq[byte]]("value1")) - -let (found, value) = db.get("key1") - -db.delete("key1") - -db.close() -``` - -## ویژگی‌ها - -- **بهینه برای نوشتن**: ساختار log-only اضافه‌شونده -- **دوام**: WAL تضمین‌کننده بازیابی پس از خرابی -- **Bloom Filter**: جستجوهای منفی سریع -- **Compaction**: استراتژی size-tiered -- **Page Cache**: کش LRU \ No newline at end of file diff --git a/docs/fa/mcp.md b/docs/fa/mcp.md deleted file mode 100644 index 5e737ad..0000000 --- a/docs/fa/mcp.md +++ /dev/null @@ -1,109 +0,0 @@ -# سرور 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/fa/monitoring.md b/docs/fa/monitoring.md deleted file mode 100644 index 0b42716..0000000 --- a/docs/fa/monitoring.md +++ /dev/null @@ -1,78 +0,0 @@ -# پایش و مشاهده‌پذیری - -## بررسی‌های سلامت - -### endpoint سلامت HTTP - -```bash -curl http://localhost:9470/health -``` - -پاسخ: - -```json -{ - "status": "healthy", - "version": "0.1.0", - "uptime_seconds": 86400, - "checks": { - "storage": "ok", - "memory": "ok", - "connections": "ok" - } -} -``` - -## معیارها - -### معیارهای سازگار با Prometheus - -```bash -curl http://localhost:9470/metrics -``` - -### معیارهای JSON - -```bash -curl http://localhost:9470/metrics?format=json -``` - -## لاگ‌گذاری - -### سطوح لاگ - -| سطح | توضیح | -|------|--------| -| `debug` | عملیات داخلی تفصیلی | -| `info` | عملیات عادی | -| `warn` | مشکلات قابل بازیابی | -| `error` | خطاهای نیازمند توجه | - -### لاگ‌های JSON ساختاریافته - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/baradb.log \ -./build/baradadb -``` - -## Grafana - -پنل‌های کلیدی: -- Queries per second -- Latency درصدها (p50, p95, p99) -- اندازه ذخیره‌سازی -- نرخ hit کش -- اتصالات فعال -- نرخ تراکنش -- نرخ خطا - -## عیب‌یابی با معیارها - -| علامت | معیار | عمل | -|-------|-------|-----| -| کوئری‌های کند | `baradb_queries_duration_seconds` | بررسی نرخ hit کش | -| حافظه بالا | `process_resident_memory_bytes` | کاهش اندازه‌های memtable/cache | -| رشد ذخیره‌سازی | `baradb_storage_lsm_size_bytes` | اجرای فشرده‌سازی دستی | -| خطاهای اتصال | `baradb_active_connections` | افزایش استخر اتصال | \ No newline at end of file diff --git a/docs/fa/performance.md b/docs/fa/performance.md deleted file mode 100644 index a466cef..0000000 --- a/docs/fa/performance.md +++ /dev/null @@ -1,62 +0,0 @@ -# راهنمای عملکرد - -## روش‌شناسی بنچمارک - -همه بنچمارک‌ها با Nim 2.2.0 و `-d:release --opt:speed` اجرا می‌شوند. - -## بنچمارک‌های ذخیره‌سازی - -### LSM-Tree - -| متریک | مقدار | -|--------|-------| -| توان عملیاتی نوشتن | ~580,000 ops/s | -| توان عملیاتی خواندن | ~720,000 ops/s | - -### B-Tree - -| متریک | مقدار | -|--------|-------| -| توان عملیاتی درج | ~1,200,000 ops/s | -| جستجوی نقطه‌ای | ~1,500,000 ops/s | - -## بنچمارک‌های موتور برداری - -### HNSW - -| متریک | مقدار | -|--------|-------| -| درج (dim=128) | ~45,000 vectors/s | -| جستجوی top-10 (n=100K) | ~8 ms | - -## بنچمارک‌های پروتکل - -| پروتکل | اتصال | کوئری/ثانیه | -|--------|-------|--------------| -| Binary | 1 | 45,000 | -| Binary | 100 | 380,000 | -| HTTP/REST | 1 | 12,000 | - -## راهنمای تنظیم - -### برای بار کاری سنگین نوشتن - -```bash -BARADB_MEMTABLE_SIZE_MB=256 -BARADB_WAL_SYNC_INTERVAL_MS=10 -``` - -### برای بار کاری سنگین خواندن - -```bash -BARADB_CACHE_SIZE_MB=1024 -BARADB_BLOOM_BITS_PER_KEY=10 -``` - -### برای جستجوی برداری - -```bash -BARADB_VECTOR_EF_CONSTRUCTION=200 -BARADB_VECTOR_EF_SEARCH=128 -BARADB_VECTOR_M=32 -``` \ No newline at end of file diff --git a/docs/fa/protocol.md b/docs/fa/protocol.md deleted file mode 100644 index a900a1f..0000000 --- a/docs/fa/protocol.md +++ /dev/null @@ -1,67 +0,0 @@ -# مرجع پروتکل - -BaraDB چندین پروتکل پشتیبانی می‌کند: -- **Binary Wire Protocol** — با کارایی بالا -- **HTTP/REST API** — مستقل از زبان -- **WebSocket** — استریمینگ و pub/sub - -## Binary Wire Protocol - -از کدگذاری big-endian استفاده می‌کند. - -### چرخه اتصال - -``` -Client Server - | | - |─── TCP connect ──────────────>| - |─── Auth message ─────────────>| - |<── Auth_OK / Error ───────────| - |─── Query message ────────────>| - |<── Data / Complete / Error ───| -``` - -### فرمت پیام - -``` -┌─────────────┬─────────────┬─────────────┬─────────────────────┐ -│ Length │ Type │ Sequence │ Payload │ -│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ -└─────────────┴─────────────┴─────────────┴─────────────────────┘ -``` - -### انواع پیام - -| نوع | ID | توضیح | -|----|----|--------| -| Query | 0x01 | اجرای کوئری | -| Insert | 0x02 | درج داده | -| Update | 0x03 | به‌روزرسانی | -| Delete | 0x04 | حذف | -| Ready | 0x05 | آماده | -| Error | 0x06 | پاسخ خطا | - -## HTTP/REST API - -Base URL: `http://localhost:9470/api/v1` - -### Endpoints - -#### Health - -```http -GET /health -``` - -#### Query - -```http -POST /query -{ - "query": "SELECT * FROM users" -} -``` - -## WebSocket Protocol - -URL: `ws://localhost:9471` \ No newline at end of file diff --git a/docs/fa/quickstart.md b/docs/fa/quickstart.md deleted file mode 100644 index b1a5766..0000000 --- a/docs/fa/quickstart.md +++ /dev/null @@ -1,134 +0,0 @@ -# راهنمای شروع سریع BaraDB - -## شروع سرور - -پس از ساخت BaraDB، سرور را_START کنید: - -```bash -./build/baradadb -``` - -سرور به‌صورت پیش‌فرض روی `localhost:9470` شروع می‌شود. - -## اتصال از طریق CLI - -BaraDB شامل یک شل تعاملی است: - -```bash -./build/baradadb --shell -``` - -## عملیات پایه - -### ایجاد طرحواره - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; -``` - -### درج داده - -```sql -INSERT Person { name := 'Alice', age := 30 }; -INSERT Person { name := 'Bob', age := 25 }; -``` - -### پرس‌وجوی داده - -```sql -SELECT name, age FROM Person WHERE age > 18; -``` - -### به‌روزرسانی داده - -```sql -UPDATE Person SET age = 31 WHERE name = 'Alice'; -``` - -### حذف داده - -```sql -DELETE FROM Person WHERE name = 'Bob'; -``` - -## پرس‌وجوهای پیشرفته - -### JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -### تجمیع‌ها - -```sql -SELECT department, count(*), avg(salary) -FROM employees -GROUP BY department -HAVING count(*) > 5; -``` - -### CTEها - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## جستجوی برداری - -```sql --- درج بردار -INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] }; - --- جستجوی مشابه -SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10; -``` - -## عملیات گراف - -```sql --- تطبیق الگوی گراف -MATCH (p:Person)-[:KNOWS]->(other:Person) -WHERE p.name = 'Alice' -RETURN other.name; -``` - -## جستجوی تمام‌متن - -```sql --- جستجوی اسناد -SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database'); -``` - -## HTTP/REST API - -```bash -# درخواست GET -curl http://localhost:9470/api/users - -# درخواست POST -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 30}' -``` - -## مراحل بعدی - -- [مرجع BaraQL](baraql.md) -- [موتورهای ذخیره‌سازی](storage.md) -- [بررسی معماری](architecture.md) -- [مرجع پروتکل](protocol.md) \ No newline at end of file diff --git a/docs/fa/schema.md b/docs/fa/schema.md deleted file mode 100644 index 654d7aa..0000000 --- a/docs/fa/schema.md +++ /dev/null @@ -1,46 +0,0 @@ -# سیستم طرحواره - -BaraDB از طراحی schema-first با وراثت نوع و مهاجرت‌های خودکار استفاده می‌کند. - -## تعریف انواع - -```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) -``` - -## وراثت نوع - -```nim -let employee = newType("Employee") -employee.setBases(@["Person"]) -employee.addProperty("department", "str") -s.addType("default", employee) -``` - -## عملیات طرحواره - -### Diff - -```nim -let diff = s.diff(oldSchema, newSchema) -``` - -## انواع ویژگی - -| نوع | توضیح | -|-----|--------| -| `str` | رشته | -| `int32` | عدد صحیح 32 بیتی | -| `int64` | عدد صحیح 64 بیتی | -| `float32` | عدد اعشاری 32 بیتی | -| `float64` | عدد اعشاری 64 بیتی | -| `bool` | بولی | -| `datetime` | تاریخ/زمان | -| `bytes` | داده باینری | \ No newline at end of file diff --git a/docs/fa/security.md b/docs/fa/security.md deleted file mode 100644 index df0657c..0000000 --- a/docs/fa/security.md +++ /dev/null @@ -1,120 +0,0 @@ -# راهنمای امنیت - -## رمزنگاری TLS/SSL - -BaraDB از TLS 1.3 برای تمام پروتکل‌ها (باینری، HTTP، WebSocket) پشتیبانی می‌کند. اگر گواهی ارائه نشود، سرور در هنگام راه‌اندازی یک گواهی خودامضا تولید می‌کند. - -### استفاده از گواهی‌های سفارشی - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_CERT_FILE=/etc/baradb/server.crt \ -BARADB_KEY_FILE=/etc/baradb/server.key \ -./build/baradadb -``` - -### تولید گواهی‌های خودامضا - -```bash -openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ - -days 365 -nodes -subj "/CN=localhost" -``` - -### Let's Encrypt (تولید) - -از certbot استفاده کنید و BaraDB را به فایل‌های تولیدشده هدایت کنید: - -```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 -``` - -## احراز هویت - -### احراز هویت مبتنی بر JWT - -BaraDB از JWT با امضای HMAC-SHA256 استفاده می‌کند. - -#### فعال‌سازی احراز هویت - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -#### ایجاد توکن‌ها - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("your-secret-key") -let token = am.createToken(JWTClaims( - sub: "user1", - role: "admin", - exp: getTime() + 24.hours -)) -``` - -#### کنترل دسترسی مبتنی بر نقش - -| نقش | مجوزها | -|------|---------| -| `admin` | دسترسی کامل | -| `write` | خواندن + نوشتن | -| `read` | فقط خواندن | -| `monitor` | فقط معیارها و سلامت | - -### احراز هویت چندعاملی (MFA) - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("secret-key") -let mfaCode = am.generateTOTP("user1") -let valid = am.validateTOTP("user1", mfaCode) -``` - -## محدودیت نرخ - -محدودیت نرخ token-bucket از سوءاستفاده جلوگیری می‌کند: - -```nim -import barabadb/protocol/ratelimit - -var rl = newRateLimiter( - rlaTokenBucket, - globalRate = 10000, - perClientRate = 1000, - burstSize = 100 -) - -if not rl.allowRequest("client-ip"): - return error("محدودیت نرخ تجاوز شده") -``` - -## امنیت شبکه - -### آدرس اتصال - -به‌صورت پیش‌فرض BaraDB به `127.0.0.1` متصل می‌شود. برای تولید: - -```bash -BARADB_ADDRESS=0.0.0.0 ./build/baradadb -``` - -## چک‌لیست امنیتی - -- [ ] تغییر رمز JWT پیش‌فرض -- [ ] فعال‌سازی TLS با گواهی‌های معتبر -- [ ] اتصال به رابط‌های خاص -- [ ] فعال‌سازی احراز هویت در تولید -- [ ] پیکربندی محدودیت نرخ -- [ ] فعال‌سازی لاگ حسابرسی -- [ ] رمزنگاری داده در حالت سکون -- [ ] اجرای BaraDB به‌عنوان کاربر غیرroot -- [ ] محدود نگه‌داشتن قوانین فایروال -- [ ] چرخش منظم رمزهای JWT \ No newline at end of file diff --git a/docs/fa/storage.md b/docs/fa/storage.md deleted file mode 100644 index d24fafb..0000000 --- a/docs/fa/storage.md +++ /dev/null @@ -1,78 +0,0 @@ -# موتورهای ذخیره‌سازی - -BaraDB چندین موتور ذخیره‌سازی بهینه‌شده برای الگوهای دسترسی مختلف فراهم می‌کند. - -## LSM-Tree (کلید-مقدار) - -موتور ذخیره‌سازی اصلی با ساختار log-only اضافه‌شونده بهینه برای نوشتن. - -### استفاده - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key1", cast[seq[byte]]("value1")) -let (found, value) = db.get("key1") -db.close() -``` - -### اجزا - -- **MemTable**: بافر مرتب در حافظه -- **WAL**: log جلوگیری از نوشتن برای دوام -- **SSTable**: جداول رشته‌ای مرتب روی دیسک -- **Bloom Filter**: ساختار احتمالی برای جستجوهای منفی سریع -- **Compaction**: استراتژی size-tiered با مدیریت سطح -- **Page Cache**: کش LRU با ردیابی نرخ hit - -## اندیس B-Tree - -اندیس مرتب برای اسکن بازه‌ای و جستجوهای نقطه‌ای. - -### استفاده - -```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) - -دوام عملیات‌های نوشتن را تضمین می‌کند. - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append("txn1", "SET key1 value1") -wal.flush() -``` - -## Bloom Filter - -ساختار داده احتمالی برای جستجوهای منفی سریع. - -```nim -import barabadb/storage/bloom - -var filter = newBloomFilter(10000, 0.01) -filter.add("key1") -if filter.mightContain("key1"): - echo "احتمالاً وجود دارد" -``` - -## I/O نگاشته‌شده به حافظه - -دسترسی کارآمد به فایل با استفاده از mmap. - -```nim -import barabadb/storage/mmap - -var mapped = mmapFile("./data/file.dat") -let data = mapped.read(0, 100) -``` \ No newline at end of file diff --git a/docs/fa/transactions.md b/docs/fa/transactions.md deleted file mode 100644 index 06be083..0000000 --- a/docs/fa/transactions.md +++ /dev/null @@ -1,67 +0,0 @@ -# تراکنش‌ها و MVCC - -MVCC (کنترل همزمانی چندنسخه‌ای) با جداسازی snapshot و تشخیص بن‌بست. - -## استفاده - -```nim -import barabadb/core/mvcc - -var tm = newTxnManager() -let txn = tm.beginTxn() - -# عملیات نوشتن -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) - -# Commit -discard tm.commit(txn) -``` - -## جداسازی تراکنش - -BaraDB از **جداسازی snapshot** استفاده می‌کند: -- خوانندگان نویسندگان را مسدود نمی‌کنند -- نویسندگان خوانندگان را مسدود نمی‌کنند -- هر تراکنش یک snapshot سازگار می‌بیند - -## تشخیص بن‌بست - -```nim -import barabadb/core/deadlock - -var detector = newDeadlockDetector() -if detector.detectCycle(txn1, txn2): - echo "بن‌بست تشخیص داده شد!" -``` - -## WAL - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append(txnId, "SET key value") -wal.flush() -``` - -## Savepoints - -```nim -tm.savepoint(txn, "sp1") -tm.rollbackToSavepoint(txn, "sp1") -``` - -## تأیید رسمی - -پروتکل MVCC در TLA+ مشخص شده: - -```bash -cd formal-verification -java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla -``` \ No newline at end of file diff --git a/docs/fa/troubleshooting.md b/docs/fa/troubleshooting.md deleted file mode 100644 index 25b6134..0000000 --- a/docs/fa/troubleshooting.md +++ /dev/null @@ -1,87 +0,0 @@ -# عیب‌یابی - -## مشکلات نصب - -### Nim یافت نشد - -```bash -curl https://nim-lang.org/choosenim/init.sh -sSf | sh -``` - -### خطای کامپایل SSL - -```bash -nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim -``` - -### وابستگی‌های گم‌شده - -```bash -nimble install -d -y -``` - -## مشکلات زمان اجرا - -### پورت در حال استفاده - -```bash -BARADB_PORT=5433 ./build/baradadb -``` - -### Permission denied - -```bash -mkdir -p ./data -chmod 755 ./data -``` - -### کمبود حافظه - -```bash -BARADB_MEMTABLE_SIZE_MB=32 \ -BARADB_CACHE_SIZE_MB=128 \ -./build/baradadb -``` - -## مشکلات کوئری - -### خطای نحوی - -```sql -SELECT name, age FROM users WHERE age > 18; -``` - -### جدول یافت نشد - -```sql -CREATE TYPE User { name: str, age: int32 }; -``` - -### عدم تطابق نوع - -```sql -SELECT * FROM users WHERE age > 18; -``` - -## مشکلات اتصال - -### Connection refused - -```bash -./build/baradadb -sudo ufw allow 9472 -``` - -## مشکلات عملکرد - -### کوئری‌های کند - -1. ایجاد اندیس: `CREATE INDEX idx_users_name ON users(name);` -2. استفاده از LIMIT -3. افزایش کش: `BARADB_CACHE_SIZE_MB=1024` - -## حالت اشکال‌زدایی - -```bash -BARADB_LOG_LEVEL=debug ./build/baradadb -``` \ No newline at end of file diff --git a/docs/fa/udf.md b/docs/fa/udf.md deleted file mode 100644 index da4f1eb..0000000 --- a/docs/fa/udf.md +++ /dev/null @@ -1,46 +0,0 @@ -# توابع تعریف‌شده کاربر - -گسترش BaraQL با توابع سفارشی. - -## استفاده - -```nim -import barabadb/query/udf - -var reg = newUDFRegistry() - -reg.registerStdlib() - -reg.register("greet", @[UDFParam(name: "name", typeName: "str")], - "str", proc(args: seq[Value]): Value = - return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) -``` - -## توابع استاندارد - -| تابع | توضیح | مثال | -|------|--------|------| -| `abs(n)` | قدر مطلق | `abs(-5)` → 5 | -| `sqrt(n)` | ریشه دوم | `sqrt(16)` → 4 | -| `pow(n, e)` | توان | `pow(2, 3)` → 8 | -| `lower(s)` | حروف کوچک | `lower('ABC')` → 'abc' | -| `upper(s)` | حروف بزرگ | `upper('abc')` → 'ABC' | -| `len(s)` | طول | `len('hello')` → 5 | - -## ثبت تابع - -```nim -reg.register( - name: "my_function", - params: @[UDFParam(name: "arg1", typeName: "str")], - returnType: "str", - body: proc(args: seq[Value]): Value = - result = Value(kind: vkString, strVal: "") -) -``` - -## استفاده در کوئری - -```sql -SELECT greet(name) FROM users; -``` \ No newline at end of file diff --git a/docs/fa/vector.md b/docs/fa/vector.md deleted file mode 100644 index a15056a..0000000 --- a/docs/fa/vector.md +++ /dev/null @@ -1,57 +0,0 @@ -# موتور جستجوی برداری - -اندیس‌های HNSW و IVF-PQ برای جستجوی شباهت. - -## استفاده - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) -``` - -## انواع اندیس - -### HNSW - -گراف Navigable Small World سلسله‌مراتبی. - -```nim -var hnsw = newHNSWIndex( - dimensions = 128, - m = 16, - efConstruction = 200, - efSearch = 100 -) -``` - -### IVF-PQ - -اندیس فایل معکوس با تکمیم محصول. - -```nim -var ivfpq = newIVFPQIndex( - dimensions = 128, - numCentroids = 256, - subQuantizers = 8 -) -``` - -## معیارهای فاصله - -| معیار | توضیح | -|-------|--------| -| `cosine` | شباهت کسینوسی | -| `euclidean` | فاصله L2 | -| `dotproduct` | ضرب نقطه‌ای | -| `manhattan` | فاصله L1 | - -## کوانتیزاسیون - -```nim -let scalar = scalarQuantize(data, bits = 8) -let pq = productQuantize(data, subVectors = 8, bits = 8) -``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 1c3502e..d7fa686 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,13 +5,7 @@ ## Documentation Languages - [English](en/) -- [العربية (Arabic)](ar/) - [Български (Bulgarian)](bg/) -- [Deutsch (German)](de/) -- [فارسی (Farsi)](fa/) -- [Русский (Russian)](ru/) -- [Türkçe (Turkish)](tr/) -- [中文 (Chinese)](zh/) --- @@ -67,4 +61,4 @@ --- -*To add a new language, create a new folder in `docs/` with the language code (e.g., `docs/de/`) and add a link above.* +*To add a new language, create a new folder in `docs/` with the language code and add a link above.* diff --git a/docs/ru/api-binary.md b/docs/ru/api-binary.md deleted file mode 100644 index 90ae6b6..0000000 --- a/docs/ru/api-binary.md +++ /dev/null @@ -1,71 +0,0 @@ -# API бинарного протокола - -Низкоуровневый wire-протокол для высокопроизводительных клиентских соединений. - -## Формат сообщения - -Все сообщения используют порядок байтов big-endian: - -``` -┌────────┬────────┬────────┬────────┬─────────────┐ -│ Length │ Type │ Seq │ Status │ Payload │ -│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ -└────────┴────────┴────────┴────────┴─────────────┘ -``` - -## Типы сообщений - -### 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) -``` - -## Коды ответов - -| Код | Имя | Описание | -|-----|-----|---------| -| 0x00 | OK | Успех | -| 0x01 | ERROR | Общая ошибка | -| 0x02 | AUTH_REQUIRED | Требуется аутентификация | -| 0x03 | INVALID_QUERY | Синтаксическая ошибка запроса | -| 0x04 | NOT_FOUND | Ресурс не найден | - -## Сериализация - -```nim -import barabadb/protocol/wire - -let bytes = serializeValue(Value(kind: vkString, strVal: "test")) -let value = deserializeValue(bytes) -``` \ No newline at end of file diff --git a/docs/ru/api-http.md b/docs/ru/api-http.md deleted file mode 100644 index 315c5a3..0000000 --- a/docs/ru/api-http.md +++ /dev/null @@ -1,83 +0,0 @@ -# HTTP/REST API - -JSON-based REST API для веб-приложений. - -## Base URL - -``` -http://localhost:9470/api -``` - -## Endpoints - -### GET /api/users - -Список всех пользователей: - -```bash -curl http://localhost:9470/api/users -``` - -### GET /api/users/:id - -Получить пользователя по ID: - -```bash -curl http://localhost:9470/api/users/1 -``` - -### POST /api/users - -Создать пользователя: - -```bash -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Charlie", "age": 35}' -``` - -### PUT /api/users/:id - -Обновить пользователя: - -```bash -curl -X PUT http://localhost:9470/api/users/1 \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 31}' -``` - -### DELETE /api/users/:id - -Удалить пользователя: - -```bash -curl -X DELETE http://localhost:9470/api/users/1 -``` - -## Query Endpoint - -Выполнение BaraQL запросов через HTTP: - -```bash -curl -X POST http://localhost:9470/api/query \ - -H "Content-Type: application/json" \ - -d '{"sql": "SELECT * FROM users WHERE age > 18"}' -``` - -## Ответ об ошибке - -```json -{ - "error": { - "code": "INVALID_QUERY", - "message": "Syntax error at line 1" - } -} -``` - -## Аутентификация - -```bash -curl -H "Authorization: Bearer " \ - http://localhost:9470/api/users -``` \ No newline at end of file diff --git a/docs/ru/api-websocket.md b/docs/ru/api-websocket.md deleted file mode 100644 index 5de56b8..0000000 --- a/docs/ru/api-websocket.md +++ /dev/null @@ -1,80 +0,0 @@ -# WebSocket API - -Полнодуплексная потоковая передача для real-time лент данных и push-уведомлений. - -## Подключение - -``` -ws://localhost:9471/ws -``` - -## Пример клиента - -```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); -}; -``` - -## Формат сообщения - -```json -{ - "type": "query", - "id": "uuid", - "sql": "SELECT * FROM users" -} -``` - -## Типы сообщений - -### Запрос - -```json -{ - "type": "query", - "id": "123", - "sql": "SELECT * FROM users" -} -``` - -### Ответ - -```json -{ - "type": "result", - "id": "123", - "data": [{"id": 1, "name": "Alice"}] -} -``` - -### Подписка - -```json -{ - "type": "subscribe", - "table": "users" -} -``` - -### Push уведомление - -```json -{ - "type": "push", - "table": "users", - "action": "insert", - "data": {"id": 3, "name": "Charlie"} -} -``` \ No newline at end of file diff --git a/docs/ru/architecture.md b/docs/ru/architecture.md deleted file mode 100644 index 5c4cb70..0000000 --- a/docs/ru/architecture.md +++ /dev/null @@ -1,197 +0,0 @@ -# Архитектура BaraDB - -## Обзор - -BaraDB — это **мультимодальный движок баз данных** на языке Nim, объединяющий документное (KV), графовое, векторное, колоночное хранилище и полнотекстовый поиск в едином движке с унифицированным языком запросов **BaraQL**. - -## Слоёвая архитектура - -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. СЛОЙ КЛИЕНТА │ -│ Бинарный протокол │ HTTP/REST │ WebSocket │ Встраивание│ -├─────────────────────────────────────────────────────────┤ -│ 2. СЛОЙ ЗАПРОСОВ (BaraQL) │ -│ Лексер → Парсер → AST → IR → Оптимизатор → Кодоген │ -├─────────────────────────────────────────────────────────┤ -│ 3. ДВИЖОК ВЫПОЛНЕНИЯ │ -│ Документы │ Граф │ Векторы │ Колоночный │ FTS │ -├─────────────────────────────────────────────────────────┤ -│ 4. ХРАНИЛИЩЕ │ -│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Компактификация │ Cache│ -├─────────────────────────────────────────────────────────┤ -│ 5. РАСПРЕДЕЛЁННОСТЬ │ -│ Raft │ Шардирование │ Репликация │ Gossip │ -└─────────────────────────────────────────────────────────┘ -``` - -## Слой 1: Клиентский слой - -Несколько протоколов связи: - -- **Бинарный протокол** (`protocol/wire.nim`): Эффективный бинарный протокол в big-endian с 16 типами сообщений -- **HTTP/REST** (`core/httpserver.nim`): JSON-based REST API с многопоточностью -- **WebSocket** (`core/websocket.nim`): Полнодуплексная потоковая передача -- **Встраиваемый режим** (`storage/lsm.nim`): Прямой доступ внутри процесса - -### Управление соединениями - -- **Пул соединений** (`protocol/pool.nim`): Мин/макс лимиты соединений с таймаутом простоя -- **Ограничение скорости** (`protocol/ratelimit.nim`): Token-bucket глобальные и пери-клиент лимиты -- **Аутентификация** (`protocol/auth.nim`): JWT с HMAC-SHA256 и ролевой доступ -- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3 с автогенерируемыми сертификатами - -## Слой 2: Слой запросов (BaraQL) - -Конвейер BaraQL: - -1. **Лексер** (`query/lexer.nim`): Токенизация входных данных в 80+ типов токенов -2. **Парсер** (`query/parser.nim`): Рекурсивный нисходящий парсер, создающий AST -3. **AST** (`query/ast.nim`): 300+ строк, покрывающих 25+ видов узлов -4. **IR** (`query/ir.nim`): Промежуточное представление для планов выполнения -5. **Оптимизатор** (`query/adaptive.nim`): Адаптивная кросс-модальная оптимизация запросов -6. **Кодоген** (`query/codegen.nim`): Трансляция IR в операции хранилища -7. **Исполнитель** (`query/executor.nim`): Выполнение планов с параллелизацией - -### Кросс-модальное планирование - -Оптимизатор (`query/adaptive.nim`) определяет порядок выполнения между движками: - -``` -1. Оценить селективность каждого предиката -2. Направить наиболее селективный предикат в его движок первым -3. Использовать bloom-фильтры для KV поисков -4. Параллелизовать независимые ветви -5. Потоковая передача результатов для избежания материализации -``` - -## Слой 3: Движок выполнения - -### Документный/KV движок -- **LSM-Tree** (`storage/lsm.nim`): Хранилище с оптимизацией записи с MemTable, WAL, SSTables -- **B-Tree индекс** (`storage/btree.nim`): Упорядоченный индекс для диапазонных сканирований с COW - -### Векторный движок (`vector/`) -- **HNSW индекс** (`vector/engine.nim`): Иерархический навигируемый граф малого мира -- **IVF-PQ индекс** (`vector/engine.nim`): Инвертированный файловый индекс с продуктовым квантованием -- **SIMD операции** (`vector/simd.nim`): AVX2-оптимизированные вычисления расстояний -- **Квантование** (`vector/quant.nim`): Скалярное, продуктовое и бинарное квантование - -### Графовый движок (`graph/`) -- **Список смежности** (`graph/engine.nim`): Граф с рёберными весами -- **Алгоритмы** (`graph/engine.nim`): BFS, DFS, Dijkstra, PageRank -- **Обнаружение сообществ** (`graph/community.nim`): Алгоритм Louvain -- **Сопоставление шаблонов** (`graph/community.nim`): Изоморфизм подграфов -- **Cypher парсер** (`graph/cypher.nim`): Cypher-подобные графовые запросы - -### Полнотекстовый поиск (`fts/`) -- **Инвертированный индекс** (`fts/engine.nim`): Терм-документ индекс -- **Ранжирование** (`fts/engine.nim`): BM25 и TF-IDF scoring -- **Нечёткий поиск** (`fts/engine.nim`): Сопоставление по расстоянию Левенштейна -- **Многоязычность** (`fts/multilang.nim`): Токенизаторы для EN, BG, DE, FR, RU - -### Колоночный движок (`core/columnar.nim`) -- Поколоночное хранение для аналитических запросов -- RLE и словарное кодирование -- SIMD-ускоренные агрегаты - -## Слой 4: Хранилище - -- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTable, Bloom Filter, Компактификация -- **Page Cache** (`storage/compaction.nim`): LRU кэш с отслеживанием hit rate -- **Memory-mapped I/O** (`storage/mmap.nim`): mmap-based доступ к файлам -- **Восстановление** (`storage/recovery.nim`): WAL replay и восстановление после сбоев - -### Путь записи - -``` -Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген - → StorageOp → MVCC Txn → WAL Write → MemTable → Commit -``` - -### Путь чтения - -``` -Клиент → Протокол → Auth → Парсер → AST → IR → Кодоген - → StorageOp → MVCC Snapshot → MemTable → SSTable → Result -``` - -## Слой 5: Распределённость - -- **Raft Consensus** (`core/raft.nim`): Лидер-выборы, репликация лога -- **Шардирование** (`core/sharding.nim`): Hash, range и consistent hashing -- **Репликация** (`core/replication.nim`): Sync, async, semi-sync режимы -- **Gossip протокол** (`core/gossip.nim`): SWIM-like управление членством -- **Распределённые транзакции** (`core/disttxn.nim`): Two-phase commit - -## Ключевые архитектурные решения - -1. **Чистый Nim**: Без Cython, Python или Rust зависимостей -2. **Унифицированное хранилище**: Один движок для KV, графов, векторов, FTS и колоночного -3. **Встраиваемый режим**: Может работать как библиотека или сервер -4. **Бинарный протокол**: Кастомный эффективный wire протокол -5. **MVCC**: Многоверсионное управление параллелизмом -6. **Схема-первый**: Строго типизированная система схем с наследованием -7. **Кросс-модальность**: Единый язык запросов для всех моделей данных -8. **Формальная верификация**: Основные распределённые алгоритмы специфицированы в TLA+ и проверены с TLC - -## Статистика по модулям - -| Категория | Модули | Строк кода | Назначение | -|----------|---------|------------|------------| -| Core | 16 | ~4,200 | Сервер, протоколы, транзакции, распределённость | -| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, компактификация, mmap | -| Query | 7 | ~2,800 | Лексер, парсер, AST, IR, оптимизатор, кодоген, исполнитель | -| Vector | 3 | ~1,200 | HNSW, IVF-PQ, квантование, SIMD | -| Graph | 3 | ~1,000 | Список смежности, алгоритмы, обнаружение сообществ | -| FTS | 2 | ~900 | Инвертированный индекс, BM25, нечёткий, многоязычный | -| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, пул, auth, rate limit, SSL | -| Schema | 1 | ~600 | Типы, связи, наследование, миграции | -| Client | 2 | ~800 | Nim binary клиент, файловые хелперы | -| CLI | 1 | ~400 | Интерактивная BaraQL оболочка | -| **Всего** | **49** | **~14,100** | | - -## Диаграммы потока данных - -### Простой запрос - -``` -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ -│ Client │───→│ Lexer │───→│ Parser │───→│ IR │───→│ Codegen│ -└────────┘ └────────┘ └────────┘ └────────┘ └───┬────┘ - │ -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ -│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘ -└────────┘ └────────┘ └────────┘ └────────┘ -``` - -### Кросс-модальный запрос - -``` - ┌─────────────┐ - │ Parser │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Adaptive │ - │ Optimizer │ - └──────┬──────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ Vector │ │ Graph │ │ FTS │ - │ Engine │ │ Engine │ │ Engine │ - └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ - │ │ │ - └───────────────┼───────────────┘ - │ - ┌──────▼──────┐ - │ Join │ - │ & Sort │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Result │ - └─────────────┘ -``` \ No newline at end of file diff --git a/docs/ru/backup.md b/docs/ru/backup.md deleted file mode 100644 index 2232fbd..0000000 --- a/docs/ru/backup.md +++ /dev/null @@ -1,120 +0,0 @@ -# Резервное копирование и восстановление - -## Онлайн снэпшоты - -BaraDB поддерживает онлайн снэпшоты без остановки сервера. Снэпшот захватывает согласованное представление на момент времени с помощью MVCC. - -### Создание снэпшота - -```nim -import barabadb/core/backup - -var bm = newBackupManager() -bm.createSnapshot("/backup/baradb_2025-01-15") -``` - -### Через CLI - -```bash -./build/baradadb --snapshot --output=/backup/snapshot.db -``` - -### Через HTTP API - -```bash -curl -X POST http://localhost:9470/api/backup \ - -H "Content-Type: application/json" \ - -d '{"destination": "/backup/snapshot.db"}' -``` - -### Автоматические бэкапы - -```bash -# Ежедневный снэпшот в 2 ночи -0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db - -# Хранить последние 7 дней -find /backup -name "baradb_*.db" -mtime +7 -delete -``` - -## Восстановление на момент времени (PITR) - -BaraDB использует WAL для восстановления на момент времени. - -### Архивирование WAL - -```bash -BARADB_WAL_ARCHIVE_DIR=/backup/wal \ -BARADB_WAL_ARCHIVE_INTERVAL_MS=60000 \ -./build/baradadb -``` - -### Восстановление из снэпшота + WAL - -```bash -# Восстановление из снэпшота -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal - -# Восстановление до конкретного LSN -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal \ - --target-lsn=15420 - -# Восстановление до конкретного времени -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal \ - --target-time="2025-01-15T10:30:00Z" -``` - -### Восстановление через SQL - -```sql -RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; -``` - -## Сценарии аварийного восстановления - -### Сценарий 1: Повреждение файла - -```bash -cp /backup/sstables/000012.sst ./data/sstables/ -./build/baradadb --rebuild-index -``` - -### Сценарий 2: Полная потеря данных - -```bash -cp /backup/snapshot.db ./data/ -./build/baradadb --recover --wal-dir=/backup/wal -curl http://localhost:9470/health -``` - -### Сценарий 3: Отказ узла кластера - -```bash -BARADB_RAFT_NODE_ID=newnode \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## Проверка бэкапов - -```bash -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --data-dir=/tmp/verify_data - -curl http://localhost:9470/api/admin/check -``` - -## Рекомендации - -1. **Регулярно тестируйте восстановление** -2. **Храните бэкапы вне сайта** (S3, GCS, Azure Blob) -3. **Шифруйте бэкапы** -4. **Мониторьте задачи бэкапа** -5. **Документируйте RTO/RPO** \ No newline at end of file diff --git a/docs/ru/baraql.md b/docs/ru/baraql.md deleted file mode 100644 index 1fa395e..0000000 --- a/docs/ru/baraql.md +++ /dev/null @@ -1,597 +0,0 @@ -# Справочник по языку запросов BaraQL - -BaraQL — это совместимый с SQL язык запросов с расширениями для графовых, векторных и документных операций. - -## Типы данных - -| Тип | Описание | Пример | -|------|----------|--------| -| `null` | Null значение | `null` | -| `bool` | Булевый | `true`, `false` | -| `int8` | 8-битное знаковое целое | `127` | -| `int16` | 16-битное знаковое целое | `32767` | -| `int32` | 32-битное знаковое целое | `2147483647` | -| `int64` | 64-битное знаковое целое | `9223372036854775807` | -| `float32` | 32-битное с плавающей точкой | `3.14` | -| `float64` | 64-битное с плавающей точкой | `3.14159265359` | -| `str` | UTF-8 строка | `'hello'` | -| `bytes` | Сырые байты | `0xDEADBEEF` | -| `array` | Однородный массив | `[1, 2, 3]` | -| `vector` | Вектор float32 | `[0.1, 0.2, 0.3]` | -| `object` | Объект ключ-значение | `{"a": 1}` | -| `datetime` | timestamp ISO 8601 | `'2025-01-15T10:30:00Z'` | -| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` | -| `json` | JSON документ | `{"key": "value"}` | -| `jsonb` | Бинарный JSON (проверенный) | `{"key": "value"}` | - -## Базовые запросы - -### SELECT - -```sql --- Все столбцы -SELECT * FROM users; - --- Конкретные столбцы -SELECT name, age FROM users; - --- Псевдонимы -SELECT name AS full_name, age AS years FROM users; - --- DISTINCT -SELECT DISTINCT department FROM employees; - --- LIMIT и OFFSET -SELECT * FROM users LIMIT 10 OFFSET 20; -``` - -### WHERE - -```sql --- Операторы сравнения -SELECT * FROM users WHERE age > 18; -SELECT * FROM users WHERE age >= 18 AND age <= 65; -SELECT * FROM users WHERE name = 'Alice'; -SELECT * FROM users WHERE name != 'Bob'; - --- Диапазон -SELECT * FROM users WHERE age BETWEEN 18 AND 65; - --- Проверка принадлежности -SELECT * FROM users WHERE department IN ('Engineering', 'Sales'); - --- Поиск по шаблону -SELECT * FROM users WHERE name LIKE 'A%'; -SELECT * FROM users WHERE name ILIKE 'alice'; -- Без учёта регистра - --- Проверка на NULL -SELECT * FROM users WHERE email IS NOT NULL; - --- Логические операторы -SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales'); -``` - -### ORDER BY - -```sql --- По возрастанию (по умолчанию) -SELECT * FROM users ORDER BY age; - --- По убыванию -SELECT * FROM users ORDER BY age DESC; - --- Несколько столбцов -SELECT * FROM users ORDER BY department ASC, age DESC; -``` - -### INSERT - -```sql --- Одна строка -INSERT users { name := 'Alice', age := 30 }; - --- С явным типом -INSERT User { name := 'Alice', age := 30 }; - --- Несколько строк -INSERT users { - { name := 'Alice', age := 30 }, - { name := 'Bob', age := 25 } -}; -``` - -### UPDATE - -```sql --- Обновить все строки -UPDATE users SET status = 'active'; - --- Условное обновление -UPDATE users SET age = 31 WHERE name = 'Alice'; - --- Обновить несколько столбцов -UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice'; -``` - -### DELETE - -```sql --- Удалить все строки -DELETE FROM users; - --- Условное удаление -DELETE FROM users WHERE age < 18; -``` - -## Агрегация и группировка - -### Агрегатные функции - -| Функция | Описание | -|---------|----------| -| `count(*)` | Подсчёт всех строк | -| `count(column)` | Подсчёт не-NULL значений | -| `sum(column)` | Сумма значений | -| `avg(column)` | Среднее значение | -| `min(column)` | Минимальное значение | -| `max(column)` | Максимальное значение | -| `stddev(column)` | Стандартное отклонение | -| `variance(column)` | Дисперсия | - -### GROUP BY - -```sql -SELECT department, count(*) as emp_count, avg(salary) as avg_salary -FROM employees -GROUP BY department; - --- С HAVING -SELECT department, count(*) as emp_count -FROM employees -GROUP BY department -HAVING count(*) > 5; - --- Несколько группировок -SELECT department, role, count(*), avg(salary) -FROM employees -GROUP BY department, role; -``` - -## JOIN - -```sql --- INNER JOIN -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; - --- LEFT JOIN -SELECT u.name, o.total -FROM users u -LEFT JOIN orders o ON u.id = o.user_id; - --- RIGHT JOIN -SELECT u.name, o.total -FROM users u -RIGHT JOIN orders o ON u.id = o.user_id; - --- FULL JOIN -SELECT u.name, o.total -FROM users u -FULL JOIN orders o ON u.id = o.user_id; - --- CROSS JOIN -SELECT u.name, p.name -FROM users u -CROSS JOIN products p; - --- Несколько JOIN -SELECT u.name, o.id, p.name -FROM orders o -JOIN users u ON o.user_id = u.id -JOIN products p ON o.product_id = p.id; - --- Self JOIN -SELECT e.name, m.name as manager -FROM employees e -JOIN employees m ON e.manager_id = m.id; -``` - -## CTE (Common Table Expressions) - -```sql --- Один CTE -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; - --- Несколько CTE -WITH - recent AS ( - SELECT * FROM orders WHERE date > '2025-01-01' - ), - totals AS ( - SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id - ) -SELECT u.name, t.total -FROM users u -JOIN totals t ON u.id = t.user_id; - --- Рекурсивный CTE -WITH RECURSIVE subordinates AS ( - SELECT id, name, manager_id FROM employees WHERE name = 'CEO' - UNION ALL - SELECT e.id, e.name, e.manager_id - FROM employees e - JOIN subordinates s ON e.manager_id = s.id -) -SELECT * FROM subordinates; -``` - -## Подзапросы - -```sql --- Подзапрос в SELECT -SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count -FROM users u; - --- Подзапрос в FROM -SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active; - --- Подзапрос в WHERE (IN) -SELECT name FROM users WHERE id IN (SELECT user_id FROM orders); - --- Подзапрос в WHERE (EXISTS) -SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id); - --- Коррелированный подзапрос -SELECT name FROM users u -WHERE age > (SELECT avg(age) FROM users WHERE department = u.department); -``` - -## CASE выражения - -```sql -SELECT name, - CASE - WHEN age < 13 THEN 'child' - WHEN age < 20 THEN 'teenager' - WHEN age < 65 THEN 'adult' - ELSE 'senior' - END AS category -FROM users; - --- Простой CASE -SELECT name, - CASE department - WHEN 'Engineering' THEN 'Tech' - WHEN 'Sales' THEN 'Revenue' - ELSE 'Other' - END AS division -FROM employees; -``` - -## Операции над множествами - -```sql --- UNION (уникальные) -SELECT name FROM customers -UNION -SELECT name FROM suppliers; - --- UNION ALL (с дубликатами) -SELECT name FROM customers -UNION ALL -SELECT name FROM suppliers; - --- INTERSECT -SELECT name FROM customers -INTERSECT -SELECT name FROM suppliers; - --- EXCEPT -SELECT name FROM customers -EXCEPT -SELECT name FROM suppliers; -``` - -## Определение схемы - -### CREATE TYPE - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - --- С обязательными полями -CREATE TYPE User { - email: str REQUIRED, - name: str, - age: int32, - created_at: datetime DEFAULT now() -}; - --- Со связями -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; - --- С вычисляемыми свойствами -CREATE TYPE Employee { - name: str, - base_salary: float64, - bonus: float64, - total_compensation: float64 COMPUTED (base_salary + bonus) -}; -``` - -### Наследование - -```sql -CREATE TYPE Animal { - name: str -}; - -CREATE TYPE Dog EXTENDING Animal { - breed: str -}; - -CREATE TYPE Cat EXTENDING Animal { - indoor: bool -}; -``` - -### Индексы - -```sql -CREATE INDEX idx_users_name ON users(name); -CREATE UNIQUE INDEX idx_users_email ON users(email); -CREATE INDEX idx_users_age ON users(age) USING btree; -``` - -### DROP - -```sql -DROP TYPE User; -DROP INDEX idx_users_name; -``` - -## Векторный поиск - -```sql --- Вставка с вектором -INSERT articles { - title := 'Nim Programming', - embedding := [0.1, 0.2, 0.3, 0.4] -}; - --- Поиск по сходству (косинусное расстояние) -SELECT title FROM articles -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- Евклидово расстояние -SELECT title FROM articles -ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- Скалярное произведение -SELECT title FROM articles -ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC -LIMIT 5; - --- С фильтрацией по метаданным -SELECT title FROM articles -WHERE category = 'tech' -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; -``` - -## Графовые шаблоны - -```sql --- Найти друзей Alice -MATCH (p:Person)-[:KNOWS]->(friend:Person) -WHERE p.name = 'Alice' -RETURN friend.name; - --- Найти кратчайший путь -MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person)) -WHERE a.name = 'Alice' AND b.name = 'Bob' -RETURN path; - --- Найти все связи -MATCH (p:Person)-[r]->(other) -WHERE p.name = 'Alice' -RETURN type(r), other.name; - --- Несколько прыжков -MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) -WHERE a.name = 'Alice' -RETURN c.name; - --- С агрегатами -MATCH (p:Person)-[:KNOWS]->(friend) -RETURN p.name, count(friend) as friend_count -ORDER BY friend_count DESC; -``` - -## Полнотекстовый поиск - -```sql --- Базовый поиск -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('database programming'); - --- С оценкой релевантности -SELECT title, relevance() -FROM articles -WHERE MATCH(title, body) AGAINST('Nim language') -ORDER BY relevance() DESC; - --- Булев режим -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE); - --- Нечёткий поиск -SELECT * FROM articles -WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2); -``` - -## Транзакции - -```sql -BEGIN; -INSERT users { name := 'Alice', age := 30 }; -INSERT orders { user_id := last_insert_id(), total := 100 }; -COMMIT; - --- С точкой сохранения -BEGIN; -INSERT users { name := 'Bob', age := 25 }; -SAVEPOINT sp1; -INSERT orders { user_id := last_insert_id(), total := 200 }; --- Ой, откатываемся к точке сохранения -ROLLBACK TO sp1; -COMMIT; -``` - -## Пользовательские функции - -```sql --- Зарегистрировать UDF -CREATE FUNCTION greet(name str) -> str { - RETURN 'Hello, ' || name || '!'; -}; - --- Использовать -SELECT greet(name) FROM users; - --- Встроенные функции -SELECT abs(-5), sqrt(16), lower('HELLO'), len('test'); -``` - -## Подсказки запросов - -```sql --- Принудительно использовать индекс -SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18; - --- Принудительно приближённый векторный поиск -SELECT /*+ APPROXIMATE */ * FROM vectors -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; - --- Параллельное выполнение -SELECT /*+ PARALLEL(4) */ * FROM large_table; -``` - -## Оконные функции - -```sql --- Функции ранжирования -SELECT - name, - department, - ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn, - RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r, - DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr -FROM employees; - --- Функции значения -SELECT - name, - salary, - LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary, - LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary, - FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest, - LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive -FROM employees; - --- Функции распределения -SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees; -``` - -### Спецификации фрейма - -```sql --- ROWS фрейм -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - ROWS BETWEEN 1 PRECEDING AND CURRENT ROW -) - --- RANGE фрейм -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW -) -``` - -## Мультитенантный ERP - -BaraDB поддерживает работу нескольких компаний (арендаторов) в одной базе данных, используя **безопасность на уровне строк (RLS)** в сочетании с **переменными сессии**. - -### Переменные сессии - -```sql -SET app.tenant_id = 'company-123'; -SELECT current_setting('app.tenant_id') AS tenant; -``` - -### Текущий пользователь / роль - -```sql -SELECT current_user AS me, current_role AS my_role; -``` - -### Изоляция арендаторов через RLS - -```sql --- Включить RLS на таблице -ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; - --- Создать политику фильтрации по арендатору -CREATE POLICY tenant_isolation ON invoices - FOR SELECT USING (tenant_id = current_setting('app.tenant_id')); - --- Каждая сессия видит только свои данные -SET app.tenant_id = 'company-a'; -SELECT * FROM invoices; -- только строки company-a -``` - -### Зачем мультитенантность? - -- **Один экземпляр, много арендаторов** — не нужно запускать 100 отдельных баз данных -- **JSONB документы** — гибкая схема, легко добавлять поля для каждого арендатора -- **RLS гарантирует изоляцию** — база данных обеспечивает границы арендаторов, а не только приложение - -## Поддерживаемые ключевые слова - -| Категория | Ключевые слова | -|----------|----------| -| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT | -| DML | INSERT, UPDATE, DELETE, SET, VALUES | -| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE | -| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON | -| Set | UNION, UNION ALL, INTERSECT, EXCEPT | -| CTEs | WITH, RECURSIVE, AS | -| Case | CASE, WHEN, THEN, ELSE, END | -| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT | -| Graph | MATCH, RETURN, WHERE, shortestPath, type | -| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS | -| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> | -| JSON | ->, ->> | -| FTS | @@ (BM25 match) | -| Recovery | RECOVER TO TIMESTAMP | -| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting | -| Session | SET, current_setting, current_user, current_role | -| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING | -| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE | \ No newline at end of file diff --git a/docs/ru/btree.md b/docs/ru/btree.md deleted file mode 100644 index 5fe6eff..0000000 --- a/docs/ru/btree.md +++ /dev/null @@ -1,34 +0,0 @@ -# B-Tree индекс - -Упорядоченная индексная структура для эффективных диапазонных сканирований и точечных поисков. - -## Использование - -```nim -import barabadb/storage/btree - -var btree = newBTreeIndex[string, string]() - -btree.insert("key1", "value1") -btree.insert("key2", "value2") - -let values = btree.get("key1") - -let range = btree.scan("key_a", "key_z") - -btree.delete("key1") -``` - -## Функции - -- Упорядоченное хранение ключ-значение -- Диапазонные запросы (BETWEEN, >, <, >=, <=) -- Префиксные сканирования -- Настраиваемый размер страницы -- Поддержка итераторов - -## Сценарии использования - -- Первичные ключевые индексы -- Вторичные индексы для часто запрашиваемых столбцов -- Данные с диапазонным разбиением \ No newline at end of file diff --git a/docs/ru/changelog.md b/docs/ru/changelog.md deleted file mode 100644 index 6b2e386..0000000 --- a/docs/ru/changelog.md +++ /dev/null @@ -1,78 +0,0 @@ -# История изменений - -Все важные изменения в BaraDB документированы в этом файле. - -## [0.1.0] — 2025-01-15 - -### Добавлено - -- **Основные хранилища** - - LSM-Tree с MemTable, WAL, SSTables и size-tiered compaction - - B-Tree упорядоченный индекс с диапазонными сканированиями и MVCC copy-on-write - - Bloom фильтры для эффективного пропуска SSTable - - Memory-mapped I/O для чтения SSTable - - LRU page cache с отслеживанием hit rate - -- **Движок запросов (BaraQL)** - - SQL-совместимый лексер с 80+ типами токенов - - Рекурсивный нисходящий парсер производящий AST с 25+ видами узлов - - Промежуточное представление (IR) для планов выполнения - - Адаптивный оптимизатор запросов с кросс-модальным планированием - - Исполнитель запросов с параллелизацией - -- **Возможности BaraQL** - - SELECT, INSERT, UPDATE, DELETE - - WHERE, ORDER BY, LIMIT, OFFSET - - GROUP BY, HAVING, агрегатные функции - - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN - - CTEs с WITH - - Подзапросы (EXISTS, IN, коррелированные) - - CASE выражения - - UNION, INTERSECT, EXCEPT - -- **Векторный движок** - - HNSW индекс для приближенного поиска ближайших соседей - - IVF-PQ индекс для крупномасштабного векторного поиска - - SIMD-оптимизированные функции расстояния - - Квантование: скалярное 8-bit/4-bit, продуктовое, бинарное - -- **Графовый движок** - - Хранение списка смежности для направленных графов с весами - - BFS и DFS обходы - - Dijkstra кратчайший путь - - PageRank важность узлов - - Louvain обнаружение сообществ - - Cypher-подобный парсер графовых запросов - -- **Полнотекстовый поиск** - - Инвертированный индекс - - BM25 ранжирование - - TF-IDF оценка - - Нечёткий поиск с расстоянием Левенштейна - - Многоязычные токенизаторы - -- **Протоколы** - - Бинарный wire протокол с 16 типами сообщений - - HTTP/REST JSON API - - WebSocket потоковая передача - - Connection pooling - - JWT аутентификация - - TLS/SSL - -- **Распределенные системы** - - Raft consensus - - Hash, range и consistent-hash шардирование - - Sync/async/semi-sync репликация - - Gossip протокол - - Two-phase commit - -### Производительность - -- LSM-Tree: 580K записей/с, 720K чтений/с -- B-Tree: 1.2M вставок/с, 1.5M поисков/с -- Vector SIMD: 850K косинусных расстояний/с (dim=768) - -### Тесты - -- 262 теста в 56 тестовых наборах -- 100% прохождение \ No newline at end of file diff --git a/docs/ru/clients.md b/docs/ru/clients.md deleted file mode 100644 index 2248049..0000000 --- a/docs/ru/clients.md +++ /dev/null @@ -1,82 +0,0 @@ -# Клиентские SDK - -BaraDB предоставляет официальные клиентские библиотеки для JavaScript/TypeScript, Python, Nim и Rust. - -## JavaScript / TypeScript - -### Установка - -```bash -npm install baradb -``` - -### Основное использование - -```typescript -import { Client } from 'baradb'; - -const client = new Client('localhost', 9472); -await client.connect(); - -const result = await client.query('SELECT name, age FROM users WHERE age > 18'); -console.log(result.rows); -``` - -## Python - -### Установка - -```bash -pip install baradb -``` - -### Основное использование - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() - -result = client.query("SELECT name, age FROM users WHERE age > 18") -for row in result: - print(row["name"], row["age"]) -``` - -## Nim (Встраиваемый режим) - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("user:1", cast[seq[byte]]("Alice")) -let (found, value) = db.get("user:1") -db.close() -``` - -## Rust - -```rust -use baradb::Client; - -let mut client = Client::connect("localhost:9472").await?; -let result = client.query("SELECT name, age FROM users").await?; -``` - -## HTTP/REST (для любого языка) - -```bash -curl -X POST http://localhost:9470/api/query \ - -H "Content-Type: application/json" \ - -d '{"query": "SELECT * FROM users"}' -``` - -## Сопоставление типов данных - -| BaraDB | JavaScript | Python | Nim | Rust | -|--------|------------|--------|-----|------| -| `null` | `null` | `None` | `nil` | `Option::None` | -| `bool` | `boolean` | `bool` | `bool` | `bool` | -| `int32` | `number` | `int` | `int` | `i32` | -| `float64` | `number` | `float` | `float64` | `f64` | -| `str` | `string` | `str` | `string` | `String` | \ No newline at end of file diff --git a/docs/ru/columnar.md b/docs/ru/columnar.md deleted file mode 100644 index b246e84..0000000 --- a/docs/ru/columnar.md +++ /dev/null @@ -1,58 +0,0 @@ -# Колоночное хранилище - -Хранилище с ориентацией на столбцы для аналитических запросов и агрегаций. - -## Использование - -```nim -import barabadb/core/columnar - -var batch = newColumnBatch() -var ageCol = batch.addInt64Col("age") -var nameCol = batch.addStringCol("name") - -ageCol.appendInt64(25) -nameCol.appendString("Alice") -``` - -## Агрегации - -```nim -echo ageCol.sumInt64() -echo ageCol.avgInt64() -echo ageCol.minInt64() -echo ageCol.maxInt64() -echo ageCol.count() -``` - -## Кодирование - -### RLE (Run-Length Encoding) - -```nim -let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) -``` - -### Dictionary Encoding - -```nim -let dict = dictEncode(@["apple", "banana", "apple"]) -``` - -## Типы столбцов - -| Тип | Описание | -|-----|---------| -| `int32` | 32-битное целое | -| `int64` | 64-битное целое | -| `float32` | 32-битное с плавающей точкой | -| `float64` | 64-битное с плавающей точкой | -| `string` | Строка переменной длины | -| `bool` | Булевый | - -## Сценарии использования - -- OLAP нагрузки -- Крупномасштабные агрегации -- Хранилища данных -- Анализ временных рядов \ No newline at end of file diff --git a/docs/ru/configuration.md b/docs/ru/configuration.md deleted file mode 100644 index dfa456d..0000000 --- a/docs/ru/configuration.md +++ /dev/null @@ -1,217 +0,0 @@ -# Справочник по конфигурации BaraDB - -BaraDB можно настроить через **переменные окружения**, **конфигурационный файл** или **флаги командной строки**. - -## Приоритет - -1. Флаги командной строки (наивысший приоритет) -2. Переменные окружения -3. Конфигурационный файл (`baradb.conf` или `baradb.json`) -4. Встроенные значения по умолчанию (низший приоритет) - -## Переменные окружения - -### Сеть - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_ADDRESS` | `127.0.0.1` | Адрес привязки | -| `BARADB_PORT` | `9472` | Порт бинарного протокола TCP | -| `BARADB_HTTP_PORT` | `9470` | Порт HTTP/REST API | -| `BARADB_WS_PORT` | `9471` | Порт WebSocket | - -### Хранилище - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_DATA_DIR` | `./data` | Путь к директории данных | -| `BARADB_MEMTABLE_SIZE_MB` | `64` | Размер MemTable в МБ | -| `BARADB_CACHE_SIZE_MB` | `256` | Размер page cache в МБ | -| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | Интервал fsync для WAL (0 = при каждой записи) | -| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | Интервал фоновой компактификации | -| `BARADB_BLOOM_BITS_PER_KEY` | `10` | Биты Bloom фильтра на ключ | - -### TLS/SSL - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_TLS_ENABLED` | `false` | Включить TLS | -| `BARADB_CERT_FILE` | — | Путь к TLS сертификату | -| `BARADB_KEY_FILE` | — | Путь к TLS закрытому ключу | - -### Безопасность - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_AUTH_ENABLED` | `false` | Включить аутентификацию | -| `BARADB_JWT_SECRET` | — | Секрет для подписи JWT | -| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Глобальный лимит запросов/сек | -| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | Лимит запросов/сек на клиента | - -### Логирование - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_LOG_LEVEL` | `info` | Уровень логирования: debug, info, warn, error | -| `BARADB_LOG_FILE` | — | Путь к файлу логов (stdout если пусто) | -| `BARADB_LOG_FORMAT` | `json` | Формат логов: json, text | - -### Векторный движок - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_VECTOR_M` | `16` | HNSW параметр `M` | -| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` | -| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` | - -### Графовый движок - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | Количество итераций PageRank | -| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | Коэффициент затухания PageRank | -| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Параметр разрешения Louvain | - -### Распределённость - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_RAFT_NODE_ID` | — | Уникальный ID узла в кластере | -| `BARADB_RAFT_PEERS` | — | Список пиров через запятую | -| `BARADB_RAFT_PORT` | `9001` | Порт внутренней связи Raft | -| `BARADB_SHARD_COUNT` | `1` | Количество шардов | -| `BARADB_REPLICATION_FACTOR` | `1` | Фактор репликации | - -## Конфигурационный файл - -### baradb.conf (INI-подобный) - -```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" - } -} -``` - -## Флаги командной строки - -```bash -./build/baradadb --help -``` - -``` -BaraDB v1.1.6 — Multimodal Database Engine - -Usage: - baradadb [options] - -Options: - -c, --config Путь к конфигурационному файлу - -p, --port TCP бинарный порт (по умолчанию: 9472) - --http-port HTTP порт (по умолчанию: 9470) - --ws-port WebSocket порт (по умолчанию: 9471) - -d, --data-dir Директория данных (по умолчанию: ./data) - --tls-cert TLS сертификат - --tls-key TLS закрытый ключ - --log-level Уровень логирования: debug, info, warn, error - --log-file Путь к файлу логов - --shell Запустить интерактивную оболочку - --version Показать версию - --recover Запустить восстановление WAL - --checkpoint Чекпоинт для восстановления - -h, --help Показать эту справку -``` - -## Примеры конфигураций - -### Разработка - -```bash -./build/baradadb \ - --log-level debug \ - --data-dir ./dev_data -``` - -### Продакшен (один узел) - -```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 -``` - -### Продакшен кластер (3 узла) - -```bash -# Узел 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 -``` \ No newline at end of file diff --git a/docs/ru/crossmodal.md b/docs/ru/crossmodal.md deleted file mode 100644 index 41c94bf..0000000 --- a/docs/ru/crossmodal.md +++ /dev/null @@ -1,63 +0,0 @@ -# Кросс-модальные запросы - -Уникальная возможность BaraDB — выполнение запросов, охватывающих несколько хранилищ в одном унифицированном операторе BaraQL. - -## Обзор - -Традиционные базы данных требуют отдельных запросов и соединений на уровне приложения при работе с разными моделями данных. BaraDB оптимизирует выполнение: - -- **Документ/KV** (LSM-Tree) — структурированные записи -- **Граф** (Список смежности) — связи -- **Вектор** (HNSW/IVF-PQ) — поиск по сходству -- **Полнотекстовый** (Инвертированный индекс) — текстовый поиск -- **Колоночный** — аналитические агрегаты - -## Паттерны запросов - -### Вектор + Полнотекстовый - -```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; -``` - -### Граф + Вектор - -```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; -``` - -### Документ + Граф - -```sql -SELECT o.id, o.total, c.name -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) -); -``` - -## Оптимизация - -### Кросс-модальный планировщик - -1. Наиболее селективный фильтр первым -2. Предикаты проталкиваются в каждый движок -3. Bloom фильтры для KV поисков -4. Параллельное выполнение независимых ветвей - -## Производительность - -| Тип запроса | Латентность (10K строк) | -|-------------|--------------------------| -| FTS + Vector | 15 ms | -| Graph + Vector | 25 ms | -| FTS + Aggregate | 12 ms | \ No newline at end of file diff --git a/docs/ru/deployment.md b/docs/ru/deployment.md deleted file mode 100644 index e8f605d..0000000 --- a/docs/ru/deployment.md +++ /dev/null @@ -1,44 +0,0 @@ -# Руководство по развёртыванию - -## Docker - -### Быстрый старт - -```bash -docker build -t baradb:latest . -docker compose up -d -docker compose ps -``` - -### Файлы Docker Compose - -| Файл | Назначение | -|------|-----------| -| `docker-compose.yml` | Development | -| `docker-compose.prod.yml` | Production | - -## Порты - -| Порт | Описание | -|------|----------| -| `9472` | Binary wire protocol | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## Переменные окружения - -| Переменная | По умолчанию | Описание | -|-----------|--------------|----------| -| `BARADB_ADDRESS` | `0.0.0.0` | Адрес для прослушивания | -| `BARADB_PORT` | `9472` | Binary protocol порт | -| `BARADB_HTTP_PORT` | `9470` | HTTP порт | -| `BARADB_DATA_DIR` | `/data` | Директория для данных | - -## Production чеклист - -- [ ] Создать TLS сертификаты в `./certs/` -- [ ] Установить сильный `BARADB_JWT_SECRET` -- [ ] Настроить файрвол правила -- [ ] Настроить регулярные бэкапы -- [ ] Проверить resource limits -- [ ] Настроить мониторинг \ No newline at end of file diff --git a/docs/ru/distributed.md b/docs/ru/distributed.md deleted file mode 100644 index 7349ec8..0000000 --- a/docs/ru/distributed.md +++ /dev/null @@ -1,108 +0,0 @@ -# Распределённые системы - -BaraDB поддерживает распределённое развёртывание с консенсусом Raft, шардированием и репликацией. - -## Консенсус Raft - -Выбор лидера и репликация лога: - -```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") -``` - -## Шардирование - -Распределение данных по узлам: - -```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") -``` - -### Стратегии шардирования - -| Стратегия | Описание | -|-----------|----------| -| `ssHash` | Хэш-шардирование | -| `ssRange` | Диапазонное шардирование | -| `ssConsistent` | Консистентное хэширование | - -## Репликация - -```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) -``` - -### Режимы репликации - -| Режим | Описание | -|--------|----------| -| `rmSync` | Синхронная репликация | -| `rmAsync` | Асинхронная репликация | -| `rmSemiSync` | Полусинхронная репликация | - -## Gossip протокол - -Членство и обнаружение отказов: - -```nim -import barabadb/core/gossip - -var g = newGossipManager() -g.addNode("node1") -g.addNode("node2") -g.tick() -``` - -## Распределённые транзакции - -Двухфазный коммит: - -```nim -import barabadb/core/disttxn - -var dt = newDistributedTxn() -dt.prepare(@["node1", "node2"]) -dt.commit() -``` - -## Формальная верификация - -Основные распределённые алгоритмы формально специфицированы в TLA+ и проверены: - -- **Raft Consensus** — `formal-verification/raft.tla` - - Проверено: ElectionSafety, StateMachineSafety -- **Two-Phase Commit** — `formal-verification/twopc.tla` - - Проверено: Atomicity, NoOrphanBlocks -- **Replication** — `formal-verification/replication.tla` - - Проверено: MonotonicLsn, AcksRemovePending - -```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 -``` \ No newline at end of file diff --git a/docs/ru/docker.md b/docs/ru/docker.md deleted file mode 100644 index 14c21d7..0000000 --- a/docs/ru/docker.md +++ /dev/null @@ -1,189 +0,0 @@ -# Руководство по развёртыванию Docker - -## Быстрый старт - -```bash -# Клонировать репозиторий -git clone https://codeberg.org/baraba/baradb -cd barabaDB - -# Собрать образ -docker build -t baradb:latest . - -# Запустить с Docker Compose -docker compose up -d - -# Проверить статус -docker compose ps -docker compose logs -f -``` - -## Файлы - -| Файл | Описание | -|------|----------| -| `Dockerfile` | Multi-stage production build | -| `docker-compose.yml` | Development конфигурация | -| `docker-compose.prod.yml` | Production конфигурация | -| `docker-compose.override.yml` | Development override (автоматически загружается) | -| `docker-entrypoint.sh` | Entrypoint скрипт для инициализации | -| `.dockerignore` | Файлы, которые не копируются в образ | -| `scripts/docker-build.sh` | Helper скрипт для сборки | -| `scripts/docker-run.sh` | Helper скрипт для ручного запуска | - -## Создание образа - -```bash -# Стандартная сборка -docker build -t baradb:latest . - -# Со скриптом -./scripts/docker-build.sh - -# С конкретной версией -IMAGE_NAME=baradb VERSION=0.1.0 ./scripts/docker-build.sh -``` - -## Запуск - -### Development (docker compose) - -```bash -# Запуск в фоне -docker compose up -d - -# Остановка -docker compose down - -# Остановка и удаление volumes (ВНИМАНИЕ — удаляет данные!) -docker compose down -v - -# Просмотр логов -docker compose logs -f -``` - -### Production (docker compose) - -```bash -# Запуск с production конфигурацией -docker compose -f docker-compose.prod.yml up -d - -# Проверка healthcheck -docker compose -f docker-compose.prod.yml ps -``` - -### Ручной (docker run) - -```bash -# Со скриптом -./scripts/docker-run.sh - -# Вручную -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 -``` - -## Порты - -| Порт | Описание | -|------|----------| -| `9472` | Binary wire protocol | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## Переменные окружения - -| Переменная | По умолчанию | Описание | -|------------|--------------|----------| -| `BARADB_ADDRESS` | `0.0.0.0` | Адрес для прослушивания | -| `BARADB_PORT` | `9472` | Binary protocol порт | -| `BARADB_HTTP_PORT` | `9470` | HTTP порт | -| `BARADB_WS_PORT` | `9471` | WebSocket порт | -| `BARADB_DATA_DIR` | `/data` | Директория для данных | -| `BARADB_LOG_LEVEL` | `info` | Уровень логирования | - -## Volumes - -| Путь в контейнере | Описание | -|-------------------|----------| -| `/data` | Основная директория базы данных | -| `/data/server/wal` | Write-ahead log | -| `/data/server/sstables` | SSTable файлы | - -## Production чеклист - -- [ ] Создать TLS сертификаты в `./certs/` -- [ ] Установить сильный `BARADB_JWT_SECRET` -- [ ] Настроить файрвол правила -- [ ] Настроить регулярные бэкапы -- [ ] Проверить resource limits -- [ ] Настроить мониторинг (healthcheck, logs) - -## TLS в Docker - -1. Создайте сертификаты: -```bash -mkdir -p certs -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout certs/server.key -out certs/server.crt -``` - -2. Активируйте в `docker-compose.prod.yml`: -```yaml -environment: - - BARADB_TLS_ENABLED=true - - BARADB_CERT_FILE=/certs/server.crt - - BARADB_KEY_FILE=/certs/server.key -volumes: - - ./certs:/certs:ro -``` - -## Бэкап в Docker - -```bash -# Ручной бэкап -docker exec baradb /app/backup backup --data-dir=/data - -# Список бэкапов -docker exec baradb /app/backup list - -# Восстановление -docker exec baradb /app/backup restore --input=backup_xxx.tar.gz -``` - -## Устранение проблем - -### Контейнер не запускается - -```bash -# Проверка логов -docker compose logs -f baradb - -# Проверка статуса -docker compose ps -``` - -### Нет соединения с базой - -```bash -# Проверка экспонированных портов -docker port baradb - -# Проверка изнутри -docker exec baradb wget -qO- http://localhost:9470/health -``` - -### Permission denied на /data - -Entrypoint скрипт автоматически создаёт директории и устанавливает правильные permissions. При проблемах: - -```bash -docker exec baradb ls -la /data -docker exec baradb chown -R baradb:baradb /data -``` \ No newline at end of file diff --git a/docs/ru/fts.md b/docs/ru/fts.md deleted file mode 100644 index b2397b7..0000000 --- a/docs/ru/fts.md +++ /dev/null @@ -1,62 +0,0 @@ -# Полнотекстовый поиск - -Инвертированный индекс с ранжированием BM25 и TF-IDF для текстового поиска. - -## Использование - -```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") - -let results = idx.search("programming language") - -let tfidf = idx.searchTfidf("programming language") - -let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) - -let wild = idx.regexSearch("prog*") -``` - -## Методы ранжирования - -### BM25 - -```nim -let bm25 = idx.searchBM25("query terms") -``` - -### TF-IDF - -```nim -let tfidf = idx.searchTfidf("query terms") -``` - -## Функции поиска - -| Функция | Описание | -|---------|---------| -| Fuzzy search | Толерантность к опечаткам (расстояние Левенштейна) | -| Wildcard | Префиксные, суффиксные и инфиксные подстановки | -| Regex | Регулярные выражения | -| Phrase search | Точное совпадение фразы | -| Boolean | Операторы AND, OR, NOT | - -## SQL интерфейс - -```sql -CREATE TABLE articles (id INT PRIMARY KEY, title TEXT, body TEXT); -CREATE INDEX idx_fts ON articles(body) USING FTS; -SELECT * FROM articles WHERE body @@ 'machine learning'; -``` - -## Многоязычная поддержка - -```nim -import barabadb/fts/multilang - -var tokenizer = newTokenizer("bg") -let tokens = tokenizer.tokenize("Търсене в пълен текст") -``` \ No newline at end of file diff --git a/docs/ru/graph.md b/docs/ru/graph.md deleted file mode 100644 index b6cdffd..0000000 --- a/docs/ru/graph.md +++ /dev/null @@ -1,51 +0,0 @@ -# Графовый движок - -Хранение в виде списка смежности со встроенными алгоритмами для обходов и анализа графов. - -## Использование - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let dfs = g.dfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -``` - -## Алгоритмы - -| Алгоритм | Описание | -|----------|---------| -| `bfs` | Поиск в ширину | -| `dfs` | Поиск в глубину | -| `dijkstra` | Кратчайший взвешенный путь | -| `pageRank` | Ранжирование важности узлов | -| `louvain` | Обнаружение сообществ | -| `patternMatch` | Изоморфизм подграфов | - -## Cypher запрос - -```nim -import barabadb/graph/cypher - -var engine = newCypherEngine(g) -let results = engine.execute(""" - MATCH (p:Person)-[:KNOWS]->(friend:Person) - WHERE p.name = 'Alice' - RETURN friend.name -""") -``` - -## Сопоставление шаблонов - -```sql -MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) -WHERE a.name = 'Alice' -RETURN b.name, c.name -``` \ No newline at end of file diff --git a/docs/ru/index.md b/docs/ru/index.md deleted file mode 100644 index a7754c3..0000000 --- a/docs/ru/index.md +++ /dev/null @@ -1,59 +0,0 @@ -# BaraDB Documentation (Русский) - -**Мультимодальная система управления базами данных, написанная на Nim — 100% нативная, без зависимостей.** - -## Быстрые ссылки - -> **Примечание:** Документация на русском языке находится в разработке. Пожалуйста, обратитесь к [английской версии](../en/) для получения полной информации. - -### Начало работы -- [Установка](../en/installation.md) -- [Быстрый старт](../en/quickstart.md) -- [Обзор архитектуры](../en/architecture.md) -- [Конфигурация](../en/configuration.md) -- [Руководство по развёртыванию](../en/deployment.md) - -### Основные концепции -- [BaraQL — язык запросов](../en/baraql.md) -- [Подсистема хранения данных](../en/storage.md) -- [Система схем](../en/schema.md) -- [Кросс-модальные запросы](../en/crossmodal.md) - -### Движки -- [LSM-Tree](../en/lsm.md) -- [B-Tree индекс](../en/btree.md) -- [Векторный поиск](../en/vector.md) -- [Графовый движок](../en/graph.md) -- [Полнотекстовый поиск](../en/fts.md) -- [Колоночное хранение](../en/columnar.md) - -### API и клиенты -- [Клиентские SDK](../en/clients.md) -- [Бинарный протокол](../en/api-binary.md) -- [HTTP/REST API](../en/api-http.md) -- [WebSocket API](../en/api-websocket.md) -- [Справка по протоколу](../en/protocol.md) - -### Операции -- [Производительность](../en/performance.md) -- [Безопасность](../en/security.md) -- [Мониторинг](../en/monitoring.md) -- [Резервное копирование](../en/backup.md) -- [Устранение неполадок](../en/troubleshooting.md) - -### Продвинутые темы -- [Транзакции и MVCC](../en/transactions.md) -- [Распределённые системы](../en/distributed.md) -- [Пользовательские функции](../en/udf.md) - ---- - -## Информация о проекте - -- [Changelog](../en/changelog.md) -- [Лицензия](../../LICENSE) -- [GitHub Repository](https://github.com/katehonz/barabaDB) - ---- - -*Документация на русском языке готовится к публикации.* \ No newline at end of file diff --git a/docs/ru/installation.md b/docs/ru/installation.md deleted file mode 100644 index 95a261b..0000000 --- a/docs/ru/installation.md +++ /dev/null @@ -1,309 +0,0 @@ -# BaraDB - Руководство по установке - -## Требования - -- **Компилятор Nim** >= 2.2.0 -- **Заголовочные файлы OpenSSL** (для поддержки TLS) -- **Операционная система**: Linux, macOS, Windows - -### Поддерживаемые платформы - -| ОС | Архитектура | Статус | -|----|--------------|--------| -| Linux | x86_64 | ✅ Полная поддержка | -| Linux | ARM64 | ✅ Полная поддержка | -| macOS | x86_64 | ✅ Полная поддержка | -| macOS | ARM64 (Apple Silicon) | ✅ Полная поддержка | -| Windows | x86_64 | ✅ Поддерживается | -| FreeBSD | x86_64 | 🟡 Тестировалось сообществом | - -## Установка Nim - -### Linux - -```bash -# Официальный установщик -curl https://nim-lang.org/choosenim/init.sh -sSf | sh - -# Ubuntu/Debian -sudo apt-get update -sudo apt-get install nim - -# Fedora -sudo dnf install nim - -# Arch Linux -sudo pacman -S nim -``` - -### macOS - -```bash -# Homebrew -brew install nim - -# MacPorts -sudo port install nim -``` - -### Windows - -```powershell -# Using choosenim -curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell - - -# Using winget -winget install nim - -# Using scoop -scoop install nim -``` - -### Проверка установки - -```bash -nim --version -# Ожидается: Nim Compiler Version 2.2.0 или выше -``` - -## Установка OpenSSL - -### Linux - -```bash -# Ubuntu/Debian -sudo apt-get install libssl-dev - -# Fedora -sudo dnf install openssl-devel - -# Arch Linux -sudo pacman -S openssl -``` - -### macOS - -OpenSSL уже включён в систему. При необходимости: - -```bash -brew install openssl -``` - -### Windows - -OpenSSL поставляется вместе с Nim для Windows. Для ручной сборки, -скачайте с [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html). - -## Сборка BaraDB - -### Клонирование репозитория - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB -``` - -### Установка зависимостей - -```bash -nimble install -d -y -``` - -### Варианты сборки - -#### Отладочная сборка - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -#### Релизная сборка (Рекомендуется) - -```bash -nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim -``` - -#### Использование Nimble Tasks - -```bash -# Отладочная сборка -nimble build_debug - -# Релизная сборка -nimble build_release -``` - -#### Уменьшение размера бинарника - -```bash -nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim -strip build/baradadb -``` - -### Проверка сборки - -```bash -./build/baradadb --version -# Ожидается: BaraDB v1.1.6 — Multimodal Database Engine -``` - -## Запуск тестов - -### Все тесты - -```bash -nim c -d:ssl -r tests/test_all.nim -``` - -### Конкретные наборы тестов - -```bash -# Тесты хранилища -nim c -d:ssl -r tests/test_storage.nim - -# Тесты движка запросов -nim c -d:ssl -r tests/test_query.nim - -# Тесты протокола -nim c -d:ssl -r tests/test_protocol.nim -``` - -### Бенчмарки - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## Варианты установки - -### Системная установка - -```bash -# Собираем релизный бинарник -nimble build_release - -# Устанавливаем в /usr/local/bin -sudo cp build/baradadb /usr/local/bin/ -sudo chmod +x /usr/local/bin/baradadb - -# Создаём директорию для данных -sudo mkdir -p /var/lib/baradb -sudo chmod 755 /var/lib/baradb -``` - -### Предварительно собранный бинарник - -Скачайте последний релиз для вашей платформы: - -```bash -# Linux x86_64 -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 - -# Linux ARM64 -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64 -chmod +x baradadb-linux-arm64 -mv baradadb-linux-arm64 /usr/local/bin/baradadb - -# macOS -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64 -chmod +x baradadb-darwin-amd64 -mv baradadb-darwin-amd64 /usr/local/bin/baradadb -``` - -### Docker - -```bash -# Скачать официальный образ -docker pull barabadb/barabadb:latest - -# Запустить -docker run -d \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - barabadb/barabadb -``` - -### Docker Compose - -```bash -docker-compose up -d -``` - -### Встраиваемое использование (Nim проекты) - -Добавьте в ваш файл `.nimble`: - -```nim -requires "barabadb >= 0.1.0" -``` - -Используйте в коде: - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## Первый запуск - -```bash -# Запуск сервера -./build/baradadb - -# Ожидаемый вывод: -# BaraDB v1.1.6 — Multimodal Database Engine -# BaraDB TCP listening on 127.0.0.1:9472 - -# Проверка через HTTP API -curl http://localhost:9470/health - -# Интерактивная оболочка -./build/baradadb --shell -``` - -## Устранение проблем при установке - -### "cannot open file: hunos" - -```bash -nimble install -d -y -``` - -### "BaraDB requires SSL support" - -Всегда компилируйте с `-d:ssl`: - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -### Медленная компиляция - -Используйте параллельную компиляцию: - -```bash -nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim -``` - -### Большой размер бинарника - -Используйте оптимизацию размера: - -```bash -nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim -``` - -## Следующие шаги - -- [Руководство по быстрому старту](quickstart.md) -- [Справочник по конфигурации](configuration.md) -- [Обзор архитектуры](architecture.md) -- [Язык запросов BaraQL](baraql.md) \ No newline at end of file diff --git a/docs/ru/lsm.md b/docs/ru/lsm.md deleted file mode 100644 index 4a7d539..0000000 --- a/docs/ru/lsm.md +++ /dev/null @@ -1,61 +0,0 @@ -# LSM-Tree хранилище - -Основной движок хранилища в BaraDB с архитектурой Log-Structured Merge-Tree. - -## Архитектура - -``` -┌─────────────────────────────────────────────┐ -│ Writes │ -│ (append to WAL + MemTable) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ MemTable │ -│ (in-memory sorted buffer) │ -└─────────────────────────────────────────────┘ - │ - (when full, flush to SSTable) - │ - ▼ -┌─────────────────────────────────────────────┐ -│ SSTable │ -│ (sorted string table on disk) │ -└─────────────────────────────────────────────┘ -``` - -## Использование - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") - -db.put("key1", cast[seq[byte]]("value1")) - -let (found, value) = db.get("key1") - -db.delete("key1") - -db.close() -``` - -## Функции - -- **Оптимизация записи**: Append-only log структура -- **Долговечность**: Write-ahead log (WAL) обеспечивает восстановление после сбоев -- **Bloom Filter**: Быстрые отрицательные поиски -- **Compaction**: Size-tiered стратегия объединяет SSTables -- **Page Cache**: LRU кэш для часто доступных страниц - -## Конфигурация - -```nim -var db = newLSMTree( - path = "./data", - memTableSize = 64 * 1024 * 1024, - walEnabled = true, - bloomFpRate = 0.01 -) -``` \ No newline at end of file diff --git a/docs/ru/mcp.md b/docs/ru/mcp.md deleted file mode 100644 index 17a467c..0000000 --- a/docs/ru/mcp.md +++ /dev/null @@ -1,109 +0,0 @@ -# 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/ru/monitoring.md b/docs/ru/monitoring.md deleted file mode 100644 index 407a7ec..0000000 --- a/docs/ru/monitoring.md +++ /dev/null @@ -1,148 +0,0 @@ -# Мониторинг и наблюдаемость - -## Проверки здоровья - -### HTTP endpoint проверки здоровья - -```bash -curl http://localhost:9470/health -``` - -Ответ: - -```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 -``` - -Возвращает `200 OK` когда сервер готов принимать трафик, `503` во время запуска. - -## Метрики - -### Prometheus-совместимые метрики - -```bash -curl http://localhost:9470/metrics -``` - -Пример вывода: - -``` -# 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 - -# 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_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 -``` - -### Метрики в формате JSON - -```bash -curl http://localhost:9470/metrics?format=json -``` - -## Логирование - -### Уровни логирования - -| Уровень | Описание | -|---------|----------| -| `debug` | Детальные внутренние операции | -| `info` | Нормальные операции | -| `warn` | Восстанавливаемые проблемы | -| `error` | Сбои требующие внимания | - -### Структурированные JSON логи - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/baradb.log \ -./build/baradadb -``` - -Пример записи лога: - -```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" -} -``` - -## Grafana Dashboard - -Импортируйте dashboard ID `baradb-001` или используйте JSON в `monitoring/grafana-dashboard.json`. - -Ключевые панели: -- Queries per second -- Query latency percentiles (p50, p95, p99) -- Storage size and SSTable count -- Cache hit rate -- Active connections -- Transaction rate -- Error rate - -## Мониторинг кластера - -```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 -} -``` - -## Устранение проблем с метриками - -| Симптом | Метрика | Действие | -|---------|---------|----------| -| Медленные запросы | `baradb_queries_duration_seconds` | Проверить cache hit rate, добавить индексы | -| Высокая память | `process_resident_memory_bytes` | Уменьшить размеры memtable/cache | -| Рост хранилища | `baradb_storage_lsm_size_bytes` | Запустить ручную компактификацию | -| Ошибки соединений | `baradb_active_connections` | Увеличить пул или добавить узлы | -| Отставание репликации | `baradb_replication_lag_ms` | Проверить сеть, увеличить ресурсы | \ No newline at end of file diff --git a/docs/ru/performance.md b/docs/ru/performance.md deleted file mode 100644 index 93bd712..0000000 --- a/docs/ru/performance.md +++ /dev/null @@ -1,95 +0,0 @@ -# Руководство по производительности - -## Методология бенчмаркинга - -Все бенчмарки запускаются с: -- **Компилятор**: Nim 2.2.0 с `-d:release --opt:speed` -- **CPU**: AMD Ryzen 9 5900X (12 cores / 24 threads) -- **Память**: 64 GB DDR4-3600 -- **Хранилище**: Samsung 980 Pro NVMe SSD -- **OS**: Ubuntu 24.04 LTS - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## Бенчмарки хранилища - -### LSM-Tree Key-Value - -| Метрика | Значение | -|---------|----------| -| Пропускная способность записи | ~580,000 ops/s | -| Пропускная способность чтения | ~720,000 ops/s | -| Средняя латентность записи | 1.7 µs | -| Средняя латентность чтения | 1.4 µs | - -### B-Tree индекс - -| Метрика | Значение | -|---------|----------| -| Пропускная способность вставки | ~1,200,000 ops/s | -| Пропускная способность точечного поиска | ~1,500,000 ops/s | -| Диапазонное сканирование (1000 ключей) | ~0.3 ms | - -## Бенчмарки векторного движка - -### HNSW индекс - -| Метрика | Значение | -|---------|----------| -| Вставка (dim=128) | ~45,000 vectors/s | -| Поиск top-10 (dim=128, n=100K) | ~8 ms | -| Память на вектор (dim=128) | ~580 bytes | - -Параметры: `M=16`, `efConstruction=200`, `efSearch=64`. - -### SIMD функции расстояния - -| Операция | 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 | - -## Бенчмарки протоколов - -| Протокол | Соединения | Запросов/сек | Латентность 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 | - -## Руководство по настройке - -### Для нагрузки с интенсивной записью - -```bash -export BARADB_MEMTABLE_SIZE_MB=256 -export BARADB_WAL_SYNC_INTERVAL_MS=10 -export BARADB_COMPACTION_INTERVAL_MS=30000 -``` - -### Для нагрузки с интенсивным чтением - -```bash -export BARADB_CACHE_SIZE_MB=1024 -export BARADB_BLOOM_BITS_PER_KEY=10 -export BARADB_COMPACTION_INTERVAL_MS=120000 -``` - -### Для векторного поиска - -```bash -export BARADB_VECTOR_EF_CONSTRUCTION=200 -export BARADB_VECTOR_EF_SEARCH=128 -export BARADB_VECTOR_M=32 -``` - -### Для графовой аналитики - -```bash -export BARADB_GRAPH_PAGE_RANK_ITERATIONS=20 -export BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0 -``` \ No newline at end of file diff --git a/docs/ru/protocol.md b/docs/ru/protocol.md deleted file mode 100644 index 9cb61cf..0000000 --- a/docs/ru/protocol.md +++ /dev/null @@ -1,87 +0,0 @@ -# Справочник по протоколу - -BaraDB поддерживает несколько протоколов для клиентской коммуникации: -- **Binary Wire Protocol** — высокопроизводительный, низкая латентность -- **HTTP/REST API** — независимый от языка, легко отлаживать -- **WebSocket** — потоковая передача и pub/sub - -## Binary Wire Protocol - -Использует big-endian кодирование для всех многобайтовых значений. - -### Цикл соединения - -``` -Client Server - | | - |─── TCP connect ──────────────>| - |<── TLS handshake (optional) ──| - |─── Auth message ─────────────>| - |<── Auth_OK / Error ───────────| - |─── Query message ────────────>| - |<── Data / Complete / Error ───| - |─── Close message ────────────>| - |<── TCP close ─────────────────| -``` - -### Формат сообщения - -``` -┌─────────────┬─────────────┬─────────────┬─────────────────────┐ -│ Length │ Type │ Sequence │ Payload │ -│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ -└─────────────┴─────────────┴─────────────┴─────────────────────┘ -``` - -### Типы сообщений - -| Тип | ID | Направление | Описание | -|----|----|-------------|---------| -| Query | 0x01 | C→S | Выполнить запрос | -| Insert | 0x02 | C→S | Вставить данные | -| Update | 0x03 | C→S | Обновить данные | -| Delete | 0x04 | C→S | Удалить данные | -| Ready | 0x05 | S→C | Готов к следующей команде | -| Error | 0x06 | S→C | Ответ об ошибке | - -## HTTP/REST API - -Base URL: `http://localhost:9470/api/v1` - -### Endpoints - -#### Health - -```http -GET /health -``` - -#### Query - -```http -POST /query -Content-Type: application/json - -{ - "query": "SELECT name, age FROM users WHERE age > 18" -} -``` - -#### Schema - -```http -GET /schema -``` - -## WebSocket Protocol - -URL: `ws://localhost:9471` - -### Pub/Sub - -```javascript -ws.send(JSON.stringify({ - type: 'subscribe', - table: 'users' -})); -``` \ No newline at end of file diff --git a/docs/ru/quickstart.md b/docs/ru/quickstart.md deleted file mode 100644 index d05ba97..0000000 --- a/docs/ru/quickstart.md +++ /dev/null @@ -1,134 +0,0 @@ -# BaraDB - Руководство по быстрому старту - -## Запуск сервера - -После сборки BaraDB запустите сервер: - -```bash -./build/baradadb -``` - -Сервер запустится на `localhost:9470` по умолчанию. - -## Подключение через CLI - -BaraDB включает интерактивную оболочку: - -```bash -./build/baradadb --shell -``` - -## Основные операции - -### Создание схемы - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; -``` - -### Вставка данных - -```sql -INSERT Person { name := 'Alice', age := 30 }; -INSERT Person { name := 'Bob', age := 25 }; -``` - -### Запрос данных - -```sql -SELECT name, age FROM Person WHERE age > 18; -``` - -### Обновление данных - -```sql -UPDATE Person SET age = 31 WHERE name = 'Alice'; -``` - -### Удаление данных - -```sql -DELETE FROM Person WHERE name = 'Bob'; -``` - -## Продвинутые запросы - -### JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -### Агрегатные функции - -```sql -SELECT department, count(*), avg(salary) -FROM employees -GROUP BY department -HAVING count(*) > 5; -``` - -### CTE (Common Table Expressions) - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## Векторный поиск - -```sql --- Вставка вектора -INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] }; - --- Поиск похожих -SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10; -``` - -## Графовые операции - -```sql --- Сопоставление графового шаблона -MATCH (p:Person)-[:KNOWS]->(other:Person) -WHERE p.name = 'Alice' -RETURN other.name; -``` - -## Полнотекстовый поиск - -```sql --- Поиск в документах -SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database'); -``` - -## HTTP/REST API - -```bash -# GET запрос -curl http://localhost:9470/api/users - -# POST запрос -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 30}' -``` - -## Следующие шаги - -- [Справочник по BaraQL](baraql.md) -- [Хранилища данных](storage.md) -- [Обзор архитектуры](architecture.md) -- [Справочник по протоколу](protocol.md) \ No newline at end of file diff --git a/docs/ru/schema.md b/docs/ru/schema.md deleted file mode 100644 index 96303c2..0000000 --- a/docs/ru/schema.md +++ /dev/null @@ -1,52 +0,0 @@ -# Система схем - -BaraDB использует проектирование сначала схему с наследованием типов и автоматическими миграциями. - -## Определение типов - -```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) -``` - -## Наследование типов - -```nim -let employee = newType("Employee") -employee.setBases(@["Person"]) -employee.addProperty("department", "str") -s.addType("default", employee) - -let resolved = s.resolveInheritance(employee) -``` - -## Операции со схемой - -### Diff - -```nim -let diff = s.diff(oldSchema, newSchema) -``` - -### Миграции - -Изменения схемы отслеживаются и могут генерировать скрипты миграции. - -## Типы свойств - -| Тип | Описание | -|-----|---------| -| `str` | Строка | -| `int32` | 32-битное целое | -| `int64` | 64-битное целое | -| `float32` | 32-битное с плавающей точкой | -| `float64` | 64-битное с плавающей точкой | -| `bool` | Булевый | -| `datetime` | Дата/время | -| `bytes` | Двоичные данные | \ No newline at end of file diff --git a/docs/ru/security.md b/docs/ru/security.md deleted file mode 100644 index e769527..0000000 --- a/docs/ru/security.md +++ /dev/null @@ -1,210 +0,0 @@ -# Руководство по безопасности - -## TLS/SSL шифрование - -BaraDB поддерживает TLS 1.3 для всех протоколов (бинарный, HTTP, WebSocket). Если сертификат не предоставлен, сервер автоматически генерирует самоподписанный сертификат при запуске для шифрования без конфигурации. - -### Использование пользовательских сертификатов - -```bash -# Предоставьте существующие сертификаты -BARADB_TLS_ENABLED=true \ -BARADB_CERT_FILE=/etc/baradb/server.crt \ -BARADB_KEY_FILE=/etc/baradb/server.key \ -./build/baradadb -``` - -### Генерация самоподписанных сертификатов - -```bash -openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ - -days 365 -nodes -subj "/CN=localhost" -``` - -### Let's Encrypt (Производство) - -Используйте certbot и укажите BaraDB на сгенерированные файлы: - -```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 -``` - -### TLS на стороне клиента - -```python -from baradb import Client - -client = Client("localhost", 9472, tls=True, tls_verify=True) -client.connect() -``` - -## Аутентификация - -### JWT-аутентификация - -BaraDB использует JWT (JSON Web Tokens) с подписью HMAC-SHA256. - -#### Включение аутентификации - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -#### Создание токенов - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("your-secret-key") -let token = am.createToken(JWTClaims( - sub: "user1", - role: "admin", - exp: getTime() + 24.hours -)) -``` - -#### Контроль доступа на основе ролей - -| Роль | Разрешения | -|------|------------| -| `admin` | Полный доступ | -| `write` | Чтение + запись | -| `read` | Только чтение | -| `monitor` | Только метрики и здоровье | - -#### Использование токенов - -```bash -curl -H "Authorization: Bearer $TOKEN" \ - http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -client.authenticate("eyJhbGciOiJIUzI1NiIs...") -``` - -### Многофакторная аутентификация (MFA) - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("secret-key") -# MFA на основе TOTP -let mfaCode = am.generateTOTP("user1") -let valid = am.validateTOTP("user1", mfaCode) -``` - -## Ограничение скорости - -Token-bucket ограничение скорости предотвращает злоупотребления: - -```nim -import barabadb/protocol/ratelimit - -var rl = newRateLimiter( - rlaTokenBucket, - globalRate = 10000, # 10K req/s глобально - perClientRate = 1000, # 1K req/s на клиент - burstSize = 100 # Позволить burst 100 req -) - -if not rl.allowRequest("client-ip"): - return error("Rate limit exceeded") -``` - -## Сетевая безопасность - -### Адрес привязки - -По умолчанию BaraDB привязывается к `127.0.0.1` (только localhost). Для производства: - -```bash -# Привязать ко всем интерфейсам (за файрволом или обратным прокси) -BARADB_ADDRESS=0.0.0.0 ./build/baradadb - -# Привязать к конкретному внутреннему интерфейсу -BARADB_ADDRESS=10.0.0.5 ./build/baradadb -``` - -### Правила файрвола - -```bash -# Разрешить только серверам приложений -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 - -# Заблокировать внешний доступ к портам управления -sudo ufw deny 9471 # WebSocket (только внутреннее использование) -``` - -## Шифрование данных в покое - -### Шифрование на уровне ОС - -Используйте LUKS для полнодискового шифрования: - -```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 -``` - -### Шифрование на уровне приложения - -BaraDB поддерживает прозрачное шифрование SSTable файлов: - -```bash -BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -## Аудитлог - -Все запросы и административные действия логируются: - -```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 -} -``` - -Включите аудитлог: - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/audit.log \ -./build/baradadb -``` - -## Чеклист безопасности - -- [ ] Изменить секрет JWT по умолчанию -- [ ] Включить TLS с валидными сертификатами -- [ ] Привязать к конкретным интерфейсам -- [ ] Включить аутентификацию в производстве -- [ ] Настроить ограничение скорости -- [ ] Включить аудитлог -- [ ] Шифровать данные в покое (LUKS или на уровне приложения) -- [ ] Запускать BaraDB от не-root пользователя -- [ ] Поддерживать файрвол в строгом режиме -- [ ] Регулярно менять секреты JWT \ No newline at end of file diff --git a/docs/ru/storage.md b/docs/ru/storage.md deleted file mode 100644 index 9322e6a..0000000 --- a/docs/ru/storage.md +++ /dev/null @@ -1,78 +0,0 @@ -# Хранилища данных - -BaraDB предоставляет несколько движков хранилища, оптимизированных для различных паттернов доступа. - -## LSM-Tree (Ключ-значение) - -Основной движок хранилища с оптимизацией за запись и append-only структурой лога. - -### Использование - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key1", cast[seq[byte]]("value1")) -let (found, value) = db.get("key1") -db.close() -``` - -### Компоненты - -- **MemTable**: Отсортированный буфер в памяти -- **WAL**: Write-ahead log для долговечности -- **SSTable**: Отсортированные строковые таблицы на диске -- **Bloom Filter**: Вероятностная структура для быстрых отрицательных проверок -- **Compaction**: Size-tiered стратегия с управлением уровней -- **Page Cache**: LRU кэш с отслеживанием hit rate - -## B-Tree индекс - -Упорядоченный индекс для диапазонных сканирований и точечных запросов. - -### Использование - -```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) - -Обеспечивает долговечность операций записи. - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append("txn1", "SET key1 value1") -wal.flush() -``` - -## Bloom Filter - -Вероятностная структура данных для быстрых отрицательных проверок. - -```nim -import barabadb/storage/bloom - -var filter = newBloomFilter(10000, 0.01) -filter.add("key1") -if filter.mightContain("key1"): - echo "возможно существует" -``` - -## Memory-mapped I/O - -Эффективный доступ к файлам через mmap. - -```nim -import barabadb/storage/mmap - -var mapped = mmapFile("./data/file.dat") -let data = mapped.read(0, 100) -``` \ No newline at end of file diff --git a/docs/ru/transactions.md b/docs/ru/transactions.md deleted file mode 100644 index 481157a..0000000 --- a/docs/ru/transactions.md +++ /dev/null @@ -1,78 +0,0 @@ -# Транзакции и MVCC - -MVCC (Multi-Version Concurrency Control) с изоляцией снэпшотов и обнаружением дедлоков. - -## Использование - -```nim -import barabadb/core/mvcc - -var tm = newTxnManager() -let txn = tm.beginTxn() - -# Операции записи -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) # отмена key3 - -# Commit -discard tm.commit(txn) -``` - -## Изоляция транзакций - -BaraDB использует **изоляцию снэпшотов**: -- Читатели не блокируют писателей -- Писатели не блокируют читателей -- Каждая транзакция видит согласованный снэпшот - -## Обнаружение дедлоков - -```nim -import barabadb/core/deadlock - -var detector = newDeadlockDetector() -if detector.detectCycle(txn1, txn2): - echo "Дедлок обнаружен!" -``` - -## Write-Ahead Log - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append(txnId, "SET key value") -wal.flush() -``` - -## Savepoints - -Вложенные savepoints транзакций: - -```nim -tm.savepoint(txn, "sp1") -# ... операции ... -tm.rollbackToSavepoint(txn, "sp1") -``` - -## Формальная верификация - -Протокол MVCC / Snapshot Isolation формально специфицирован в TLA+: - -- **Спецификация:** `formal-verification/mvcc.tla` -- **Проверенные свойства:** - - `NoDirtyReads` — транзакции никогда не читают незафиксированные данные - - `ReadOwnWrites` — транзакции всегда видят свои собственные записи - - `WriteWriteConflict` — первый фиксирующий выигрывает - -Запустить TLC локально: - -```bash -cd formal-verification -java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla -``` \ No newline at end of file diff --git a/docs/ru/troubleshooting.md b/docs/ru/troubleshooting.md deleted file mode 100644 index 7350e42..0000000 --- a/docs/ru/troubleshooting.md +++ /dev/null @@ -1,168 +0,0 @@ -# Руководство по устранению проблем - -## Проблемы с установкой - -### Nim не найден - -```bash -curl https://nim-lang.org/choosenim/init.sh -sSf | sh -echo 'export PATH=$HOME/.nimble/bin:$PATH' >> ~/.bashrc -source ~/.bashrc -``` - -### Ошибка компиляции SSL - -**Решение:** Всегда компилируйте с `-d:ssl`: - -```bash -nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim -``` - -### Отсутствуют зависимости - -```bash -nimble install -d -y -``` - -## Проблемы с выполнением - -### Порт уже используется - -```bash -BARADB_PORT=5433 ./build/baradadb -# или -lsof -ti:9472 | xargs kill -9 -``` - -### Permission denied - -```bash -mkdir -p ./data -chmod 755 ./data -``` - -### Недостаточно памяти - -```bash -BARADB_MEMTABLE_SIZE_MB=32 \ -BARADB_CACHE_SIZE_MB=128 \ -BARADB_VECTOR_EF_CONSTRUCTION=100 \ -./build/baradadb -``` - -### Диск заполнен - -```bash -curl -X POST http://localhost:9470/api/admin/compact -./build/baradadb --compact -``` - -## Проблемы с запросами - -### Синтаксическая ошибка - -```sql --- Правильно -SELECT name, age FROM users WHERE age > 18; - --- Неправильно (пропущена запятая) -SELECT name age FROM users WHERE age > 18; -``` - -### Таблица не найдена - -```sql -CREATE TYPE User { - name: str, - age: int32 -}; -``` - -### Несовпадение типов - -```sql --- Правильно -SELECT * FROM users WHERE age > 18; - --- Неправильно -SELECT * FROM users WHERE age > '18'; -``` - -## Проблемы с соединением - -### Connection refused - -```bash -ps aux | grep baradadb -./build/baradadb -sudo ufw allow 9472 -``` - -### Ошибка аутентификации - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="correct-secret" \ -./build/baradadb -``` - -### SSL/TLS ошибки - -```bash -BARADB_TLS_ENABLED=false ./build/baradadb -``` - -## Проблемы с производительностью - -### Медленные запросы - -```bash -curl -X POST http://localhost:9470/api/explain \ - -d '{"query": "SELECT * FROM large_table"}' -``` - -Решения: -1. Добавить индексы: `CREATE INDEX idx_users_name ON users(name);` -2. Использовать LIMIT: `SELECT * FROM users LIMIT 100;` -3. Увеличить кэш: `BARADB_CACHE_SIZE_MB=1024` - -### Высокая загрузка CPU - -```bash -BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb -``` - -### Высокое потребление памяти - -```bash -BARADB_MEMTABLE_SIZE_MB=64 -BARADB_CACHE_SIZE_MB=256 -BARADB_VECTOR_M=8 -``` - -## Проблемы кластера - -### Raft split-brain - -Убедитесь в нечётном количестве узлов (3, 5, 7). - -### Отставание репликации - -```bash -BARADB_REPLICATION_MODE=async -``` - -## Режим отладки - -```bash -BARADB_LOG_LEVEL=debug \ -BARADB_LOG_FILE=/tmp/baradb_debug.log \ -./build/baradadb -``` - -## Получение помощи - -1. Проверьте логи: `tail -f /var/log/baradb/baradb.log` -2. Проверьте метрики: `curl http://localhost:9470/metrics` -3. Запустите диагностику: `./build/baradadb --diagnose` -4. Откройте issue с версией BaraDB и логами \ No newline at end of file diff --git a/docs/ru/udf.md b/docs/ru/udf.md deleted file mode 100644 index 41ba222..0000000 --- a/docs/ru/udf.md +++ /dev/null @@ -1,51 +0,0 @@ -# Пользовательские функции - -Расширение BaraQL пользовательскими функциями. - -## Использование - -```nim -import barabadb/query/udf - -var reg = newUDFRegistry() - -reg.registerStdlib() - -reg.register("greet", @[UDFParam(name: "name", typeName: "str")], - "str", proc(args: seq[Value]): Value = - return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) -``` - -## Стандартные функции - -| Функция | Описание | Пример | -|---------|----------|--------| -| `abs(n)` | Абсолютное значение | `abs(-5)` → 5 | -| `sqrt(n)` | Квадратный корень | `sqrt(16)` → 4 | -| `pow(n, e)` | Степень | `pow(2, 3)` → 8 | -| `lower(s)` | Нижний регистр | `lower('ABC')` → 'abc' | -| `upper(s)` | Верхний регистр | `upper('abc')` → 'ABC' | -| `len(s)` | Длина | `len('hello')` → 5 | -| `trim(s)` | Обрезка пробелов | `trim(' hello ')` → 'hello' | -| `substr(s, start, len)` | Подстрока | `substr('hello', 0, 3)` → 'hel' | - -## Регистрация функции - -```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 = - result = Value(kind: vkString, strVal: "") -) -``` - -## Использование UDF в запросах - -```sql -SELECT greet(name) FROM users; -``` \ No newline at end of file diff --git a/docs/ru/vector.md b/docs/ru/vector.md deleted file mode 100644 index 33936fc..0000000 --- a/docs/ru/vector.md +++ /dev/null @@ -1,71 +0,0 @@ -# Векторный движок - -Родные индексы HNSW и IVF-PQ для поиска по сходству. - -## Использование - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) - -let filtered = idx.searchWithFilter(queryVector, k = 10, - filter = proc(meta: Table[string, string]): bool = - return meta.getOrDefault("category") == "A") -``` - -## Типы индексов - -### HNSW - -Иерархический навигируемый граф малого мира для приближенного поиска ближайших соседей. - -```nim -var hnsw = newHNSWIndex( - dimensions = 128, - m = 16, - efConstruction = 200, - efSearch = 100 -) -``` - -### IVF-PQ - -Инвертированный файловый индекс с продуктовым квантованием. - -```nim -var ivfpq = newIVFPQIndex( - dimensions = 128, - numCentroids = 256, - subQuantizers = 8 -) -``` - -## Метрики расстояния - -| Метрика | Описание | -|---------|---------| -| `cosine` | Косинусное сходство | -| `euclidean` | L2 расстояние | -| `dotproduct` | Скалярное произведение | -| `manhattan` | L1 расстояние | - -## Квантование - -```nim -import barabadb/vector/quant - -let scalar = scalarQuantize(data, bits = 8) -let pq = productQuantize(data, subVectors = 8, bits = 8) -``` - -## SIMD ускорение - -```nim -import barabadb/vector/simd - -let dist = simdCosineDistance(vec1, vec2) -``` \ No newline at end of file diff --git a/docs/tr/api-binary.md b/docs/tr/api-binary.md deleted file mode 100644 index 141a4b3..0000000 --- a/docs/tr/api-binary.md +++ /dev/null @@ -1,62 +0,0 @@ -# İkili Protokol API - -Yüksek performanslı istemci bağlantıları için düşük seviyeli wire protokolü. - -## Mesaj Formatı - -Tüm mesajlar big-endian bayt sırası kullanır: - -``` -┌────────┬────────┬────────┬────────┬─────────────┐ -│ Length │ Type │ Seq │ Status │ Payload │ -│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ -└────────┴────────┴────────┴────────┴─────────────┘ -``` - -## Mesaj Türleri - -### 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) -``` - -## Yanıt Kodları - -| Kod | Ad | Açıklama | -|-----|-----|----------| -| 0x00 | OK | Başarılı | -| 0x01 | ERROR | Genel hata | -| 0x02 | AUTH_REQUIRED | Kimlik doğrulama gerekli | -| 0x03 | INVALID_QUERY | Sözdizimi hatası | -| 0x04 | NOT_FOUND | Kaynak bulunamadı | \ No newline at end of file diff --git a/docs/tr/api-http.md b/docs/tr/api-http.md deleted file mode 100644 index dfeae83..0000000 --- a/docs/tr/api-http.md +++ /dev/null @@ -1,62 +0,0 @@ -# HTTP/REST API - -Web uygulamaları için JSON tabanlı REST API. - -## Base URL - -``` -http://localhost:9470/api -``` - -## Uç Noktalar - -### GET /api/users - -Tüm kullanıcıları listele: - -```bash -curl http://localhost:9470/api/users -``` - -### GET /api/users/:id - -ID ile kullanıcı getir: - -```bash -curl http://localhost:9470/api/users/1 -``` - -### POST /api/users - -Kullanıcı oluştur: - -```bash -curl -X POST http://localhost:9470/api/users \ - -d '{"Name": "Charlie", "age": 35}' -``` - -### PUT /api/users/:id - -Kullanıcı güncelle: - -```bash -curl -X PUT http://localhost:9470/api/users/1 \ - -d '{"Name": "Alice", "age": 31}' -``` - -### DELETE /api/users/:id - -Kullanıcı sil: - -```bash -curl -X DELETE http://localhost:9470/api/users/1 -``` - -## Sorgu Uç Noktası - -BaraQL sorgularını HTTP ile çalıştır: - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"sql": "SELECT * FROM users WHERE age > 18"}' -``` \ No newline at end of file diff --git a/docs/tr/api-websocket.md b/docs/tr/api-websocket.md deleted file mode 100644 index af085a7..0000000 --- a/docs/tr/api-websocket.md +++ /dev/null @@ -1,78 +0,0 @@ -# WebSocket API - -Gerçek zamanlı veri akışları ve anlık bildirimler için tam çift yönlü akış. - -## Bağlantı - -``` -ws://localhost:9471/ws -``` - -## İstemci Örneği - -```javascript -const ws = new WebSocket('ws://localhost:9471/ws'); - -ws.onopen = () => { - ws.send(JSON.stringify({ - type: 'query', - sql: 'SELECT * FROM users' - })); -}; - -ws.onmessage = (event) => { - console.log('Received:', JSON.parse(event.data)); -}; -``` - -## Mesaj Formatı - -```json -{ - "type": "query", - "id": "uuid", - "sql": "SELECT * FROM users" -} -``` - -## Mesaj Türleri - -### Sorgu İsteği - -```json -{ - "type": "query", - "id": "123", - "sql": "SELECT * FROM users" -} -``` - -### Sorgu Yanıtı - -```json -{ - "type": "result", - "id": "123", - "data": [{"id": 1, "name": "Alice"}] -} -``` - -### Abonelik - -```json -{ - "type": "subscribe", - "table": "users" -} -``` - -### Anlık Bildirim - -```json -{ - "type": "push", - "table": "users", - "action": "insert", - "data": {"id": 3, "name": "Charlie"} -} -``` \ No newline at end of file diff --git a/docs/tr/architecture.md b/docs/tr/architecture.md deleted file mode 100644 index 542b77e..0000000 --- a/docs/tr/architecture.md +++ /dev/null @@ -1,102 +0,0 @@ -# BaraDB Mimarisi - -## Genel Bakış - -BaraDB, Nim ile yazılmış bir **çok modlu veritabanı motorudur** — doküman (KV), grafik, vektör, kolonlu ve tam metin arama depolamasını **BaraQL** sorgu diliyle birleştirir. - -## Katmanlı Mimari - -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. İSTEMCİ KATMANI │ -│ İkili Protokol │ HTTP/REST │ WebSocket │ Gömülü │ -├─────────────────────────────────────────────────────────┤ -│ 2. SORGU KATMANI (BaraQL) │ -│ Lexer → Parser → AST → IR → Optimizör → Kod Üretimi │ -├─────────────────────────────────────────────────────────┤ -│ 3. ÇALIŞTIRMA MOTORLARI │ -│ Doküman │ Grafik │ Vektör │ Kolonlu │ FTS │ -├─────────────────────────────────────────────────────────┤ -│ 4. DEPOLAMA │ -│ LSM-Tree │ B-Tree │ WAL │ Bloom │ Sıkıştırma │ Önbellek│ -├─────────────────────────────────────────────────────────┤ -│ 5. DAĞITIK │ -│ Raft Consensus │ Parçalama │ Çoğaltma │ Gossip │ -└─────────────────────────────────────────────────────────┘ -``` - -## Katman 1: İstemci Katmanı - -- **İkili Protokol**: Verimli big-endian ikili protokol -- **HTTP/REST**: JSON tabanlı REST API -- **WebSocket**: Tam çift yönlü akış -- **Gömülü**: Süreç içi doğrudan erişim - -## Katman 2: Sorgu Katmanı (BaraQL) - -1. **Lexer** (`query/lexer.nim`): 80+ token tipi -2. **Parser** (`query/parser.nim`): Recursive descent parser -3. **AST** (`query/ast.nim`): 25+ node çeşidi -4. **IR** (`query/ir.nim`): Ara temsil -5. **Optimizör** (`query/adaptive.nim`): Çapraz modlu optimizasyon -6. **Kod Üretimi** (`query/codegen.nim`): Depolama operasyonlarına çeviri -7. **Çalıştırıcı** (`query/executor.nim`): Paralel yürütme - -## Katman 3: Çalıştırma Motorları - -### Doküman/KV Motoru -- **LSM-Tree** (`storage/lsm.nim`): MemTable, WAL, SSTables - -### Vektör Motoru (`vector/`) -- **HNSW İndeksi** (`vector/engine.nim`): Hiyerarşik Navigable Small World -- **IVF-PQ İndeksi**: Ters dosya indeksi -- **SIMD İşlemleri** (`vector/simd.nim`): AVX2-optimized - -### Grafik Motoru (`graph/`) -- BFS, DFS, Dijkstra, PageRank -- **Louvain**: Topluluk tespiti - -### Tam Metin Arama (`fts/`) -- Ters indeks, BM25, TF-IDF -- **Çok Dilli**: EN, BG, DE, FR, RU tokenizerları - -## Katman 4: Depolama - -- **LSM-Tree**: MemTable, WAL, SSTable, Bloom Filter -- **Sayfa Önbelleği**: LRU önbellek -- **Hafıza-eşlenmiş I/O**: mmap tabanlı erişim -- **Kurtarma**: WAL yeniden oynatma - -## Katman 5: Dağıtık - -- **Raft Consensus** (`core/raft.nim`): Lider seçimi, log çoğaltma -- **Parçalama** (`core/sharding.nim`): Hash, range, consistent hashing -- **Çoğaltma** (`core/replication.nim`): Sync, async, semi-sync -- **Gossip Protokolü** (`core/gossip.nim`): SWIM benzeri - -## Temel Tasarım Kararları - -1. **Saf Nim**: Cython, Python veya Rust bağımlılığı yok -2. **Birleşik Depolama**: Tek motor KV, grafik, vektör, FTS ve kolonluyi yönetir -3. **Gömülü Mod**: Kütüphane veya sunucu olarak çalışabilir -4. **İkili Protokol**: Özel verimli kablo protokolü -5. **MVCC**: Çok sürümlü eşzamanlılık kontrolü -6. **Şema-Önce**: Kalıtım destekli güçlü tipli şema sistemi -7. **Çapraz Modlu**: Tüm veri modellerinde tek sorgu dili -8. **Resmi Doğrulama**: Temel dağıtık algoritmalar TLA+'da belirtilmiş ve TLC ile model kontrolü yapılmış - -## Modül İstatistikleri - -| Kategori | Modüller | Kod Satırı | Amaç | -|----------|---------|------------|------| -| Core | 16 | ~4,200 | Sunucu, protokoller, işlemler, dağıtık | -| Storage | 7 | ~3,100 | LSM, B-Tree, WAL, bloom, sıkıştırma, mmap | -| Query | 7 | ~2,800 | Lexer, parser, AST, IR, optimizör, kod üretimi | -| Vector | 3 | ~1,200 | HNSW, IVF-PQ, nicemleme, SIMD | -| Graph | 3 | ~1,000 | Bitişik liste, algoritmalar, topluluk tespiti | -| FTS | 2 | ~900 | Ters indeks, BM25, belirsiz, çok dilli | -| Protocol | 7 | ~2,400 | Wire, HTTP, WebSocket, havuz, auth, hız sınırı | -| Schema | 1 | ~600 | Tipler, bağlantılar, kalıtım | -| Client | 2 | ~800 | Nim ikili istemcisi | -| CLI | 1 | ~400 | İnteraktif BaraQL kabuğu | -| **Toplam** | **49** | **~14,100** | | \ No newline at end of file diff --git a/docs/tr/backup.md b/docs/tr/backup.md deleted file mode 100644 index 69bcc49..0000000 --- a/docs/tr/backup.md +++ /dev/null @@ -1,82 +0,0 @@ -# Yedekleme ve Kurtarma - -## Çevrimiçi Anlık Görüntüler - -BaraDB sunucuyu durdurmadan çevrimiçi anlık görüntüleri destekler. - -### Anlık Görüntü Oluşturma - -```nim -import barabadb/core/backup - -var bm = newBackupManager() -bm.createSnapshot("/backup/baradb_2025-01-15") -``` - -### CLI ile - -```bash -./build/baradadb --snapshot --output=/backup/snapshot.db -``` - -### HTTP API ile - -```bash -curl -X POST http://localhost:9470/api/backup \ - -d '{"destination": "/backup/snapshot.db"}' -``` - -### Otomatik Yedeklemeler - -```bash -0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db -find /backup -name "baradb_*.db" -mtime +7 -delete -``` - -## Zaman Noktası Kurtarma (PITR) - -### snapshot + WAL'dan Kurtarma - -```bash -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal -``` - -### SQL ile Kurtarma - -```sql -RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; -``` - -## Felaket Kurtarma Senaryoları - -### Senaryo 1: Dosya Bozulması - -```bash -cp /backup/sstables/000012.sst ./data/sstables/ -./build/baradadb --rebuild-index -``` - -### Senaryo 2: Tam Veri Kaybı - -```bash -cp /backup/snapshot.db ./data/ -./build/baradadb --recover --wal-dir=/backup/wal -``` - -### Senaryo 3: Küme Düğümü Arızası - -```bash -BARADB_RAFT_NODE_ID=newnode \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## En İyi Uygulamalar - -1. Kurtarmayı düzenli olarak test edin -2. Yedeklemeleri uzakta saklayın (S3, GCS, Azure Blob) -3. Yedeklemeleri şifreleyin -4. Yedekleme işlerini izleyin -5. RTO/RPO'nuzu belgelendirin \ No newline at end of file diff --git a/docs/tr/baraql.md b/docs/tr/baraql.md deleted file mode 100644 index e80335c..0000000 --- a/docs/tr/baraql.md +++ /dev/null @@ -1,269 +0,0 @@ -# BaraQL - Sorgu Dili Referansı - -BaraQL, grafik, vektör ve doküman operasyonları için uzantılarla SQL uyumlu bir sorgu dilidir. - -## Veri Tipleri - -| Tip | Açıklama | Örnek | -|-----|----------|-------| -| `null` | Boş değer | `null` | -| `bool` | Boolean | `true`, `false` | -| `int8` | 8-bit işaretli tamsayı | `127` | -| `int16` | 16-bit işaretli tamsayı | `32767` | -| `int32` | 32-bit işaretli tamsayı | `2147483647` | -| `int64` | 64-bit işaretli tamsayı | `9223372036854775807` | -| `float32` | 32-bit kayan nokta | `3.14` | -| `float64` | 64-bit kayan nokta | `3.14159265359` | -| `str` | UTF-8 string | `'hello'` | -| `vector` | Float32 vektör | `[0.1, 0.2, 0.3]` | -| `datetime` | ISO 8601 zaman damgası | `'2025-01-15T10:30:00Z'` | -| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` | - -## Temel Sorgular - -### SELECT - -```sql -SELECT * FROM users; -SELECT name, age FROM users; -SELECT name AS full_name FROM users; -SELECT * FROM users LIMIT 10 OFFSET 20; -``` - -### WHERE - -```sql -SELECT * FROM users WHERE age > 18; -SELECT * FROM users WHERE age BETWEEN 18 AND 65; -SELECT * FROM users WHERE department IN ('Engineering', 'Sales'); -SELECT * FROM users WHERE name LIKE 'A%'; -``` - -### INSERT - -```sql -INSERT users { name := 'Alice', age := 30 }; -INSERT users { { name := 'Alice', age := 30 }, { name := 'Bob', age := 25 } }; -``` - -### UPDATE - -```sql -UPDATE users SET age = 31 WHERE name = 'Alice'; -``` - -### DELETE - -```sql -DELETE FROM users WHERE name = 'Bob'; -``` - -## JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -## CTE (Common Table Expressions) - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## Vektör Arama - -```sql -INSERT articles { title := 'Nim Programming', embedding := [0.1, 0.2, 0.3, 0.4] }; - -SELECT title FROM articles -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; -``` - -## Grafik Kalıpları - -```sql -MATCH (p:Person)-[:KNOWS]->(friend:Person) -WHERE p.name = 'Alice' -RETURN friend.name; -``` - -## İşlemler - -```sql -BEGIN; -INSERT users { name := 'Alice', age := 30 }; -INSERT orders { user_id := last_insert_id(), total := 100 }; -COMMIT; - --- Savepoint ile -BEGIN; -INSERT users { name := 'Bob', age := 25 }; -SAVEPOINT sp1; -INSERT orders { user_id := last_insert_id(), total := 200 }; --- Hata, savepoint'e geri al -ROLLBACK TO sp1; -COMMIT; -``` - -## Tam Metin Arama - -```sql --- Temel arama -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('database programming'); - --- İlgi puanı ile -SELECT title, relevance() -FROM articles -WHERE MATCH(title, body) AGAINST('Nim language') -ORDER BY relevance() DESC; - --- Boolean modu -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE); - --- Fuzzy arama -SELECT * FROM articles -WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2); -``` - -## Kullanıcı Tanımlı Fonksiyonlar - -```sql --- UDF kaydet -CREATE FUNCTION greet(name str) -> str { - RETURN 'Hello, ' || name || '!'; -}; - --- Kullan -SELECT greet(name) FROM users; - --- Dahili fonksiyonlar -SELECT abs(-5), sqrt(16), lower('HELLO'), len('test'); -``` - -## Sorgu İpuçları - -```sql --- İndeks kullanımını zorla -SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18; - --- Approximate vektör araması zorla -SELECT /*+ APPROXIMATE */ * FROM vectors -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; - --- Paralel çalıştırma -SELECT /*+ PARALLEL(4) */ * FROM large_table; -``` - -## Pencere Fonksiyonları - -```sql --- Sıralama fonksiyonları -SELECT - name, - department, - ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn, - RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r, - DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr -FROM employees; - --- Değer fonksiyonları -SELECT - name, - salary, - LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary, - LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary, - FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest, - LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive -FROM employees; - --- Dağılım fonksiyonları -SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees; -``` - -### Çerçeve Spesifikasyonları - -```sql --- ROWS çerçevesi -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - ROWS BETWEEN 1 PRECEDING AND CURRENT ROW -) - --- RANGE çerçevesi -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW -) -``` - -## Çok Kiracılı ERP - -BaraDB, **Satır Düzeyinde Güvenlik (RLS)** ve **oturum değişkenlerini** birleştirerek tek bir veritabanı örneğinde birden fazla şirketi (kiracı) çalıştırmayı destekler. - -### Oturum Değişkenleri - -```sql -SET app.tenant_id = 'company-123'; -SELECT current_setting('app.tenant_id') AS tenant; -``` - -### Mevcut Kullanıcı / Rol - -```sql -SELECT current_user AS me, current_role AS my_role; -``` - -### RLS Kiracı İzolasyonu - -```sql --- Tabloda RLS etkinleştir -ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; - --- Kiracıya göre filtreleme ilkesi oluştur -CREATE POLICY tenant_isolation ON invoices - FOR SELECT USING (tenant_id = current_setting('app.tenant_id')); - --- Her oturum yalnızca kendi verilerini görür -SET app.tenant_id = 'company-a'; -SELECT * FROM invoices; -- yalnızca company-a satırları -``` - -### Neden Çok Kiracılı? - -- **Bir örnek, çok kiracı** — 100 ayrı veritabanı çalıştırmaya gerek yok -- **JSONB belgeleri** — Esnek şema depolama, her kiracı için kolayca alan ekleme -- **RLS izolasyonu garanti eder** — Veritabanı kiracı sınırlarını uygular, yalnızca uygulama değil - -## Desteklenen Anahtar Kelimeler - -| Kategori | Anahtar Kelimeler | -|----------|----------| -| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT | -| DML | INSERT, UPDATE, DELETE, SET, VALUES | -| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE | -| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON | -| Set | UNION, UNION ALL, INTERSECT, EXCEPT | -| CTEs | WITH, RECURSIVE, AS | -| Case | CASE, WHEN, THEN, ELSE, END | -| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT | -| Graph | MATCH, RETURN, WHERE, shortestPath, type | -| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS | -| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> | -| JSON | ->, ->> | -| FTS | @@ (BM25 eşleşme) | -| Recovery | RECOVER TO TIMESTAMP | -| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting | -| Session | SET, current_setting, current_user, current_role | -| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING | -| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE | \ No newline at end of file diff --git a/docs/tr/btree.md b/docs/tr/btree.md deleted file mode 100644 index d95ae7e..0000000 --- a/docs/tr/btree.md +++ /dev/null @@ -1,26 +0,0 @@ -# B-Tree İndeksi - -Verimli aralık taramaları ve nokta aramaları için sıralı indeks yapısı. - -## Kullanım - -```nim -import barabadb/storage/btree - -var btree = newBTreeIndex[string, string]() - -btree.insert("key1", "value1") -btree.insert("key2", "value2") - -let values = btree.get("key1") -let range = btree.scan("key_a", "key_z") -btree.delete("key1") -``` - -## Özellikler - -- Sıralı anahtar-değer depolama -- Aralık sorguları (BETWEEN, >, <, >=, <=) -- Önek taramaları -- Yapılandırılabilir sayfa boyutu -- İteratör desteği \ No newline at end of file diff --git a/docs/tr/changelog.md b/docs/tr/changelog.md deleted file mode 100644 index 36268bb..0000000 --- a/docs/tr/changelog.md +++ /dev/null @@ -1,76 +0,0 @@ -# Değişiklik Günlüğü - -## [0.1.0] — 2025-01-15 - -### Eklenenler - -- **Çekirdek Depolama Motorları** - - MemTable, WAL, SSTables ve size-tiered compaction ile LSM-Tree - - MVCC copy-on-write ile aralık tarama ve B-Tree sıralı indeks - - Bloom filtreleri - - Memory-mapped I/O - - LRU sayfa önbelleği - -- **Sorgu Motoru (BaraQL)** - - 80+ token türüyle SQL uyumlu lexer - - 25+ düğüm türüyle AST üreten recursive descent parser - - IR ara temsili - - Çapraz modlu planlama ile adaptif sorgu optimizatörü - - Paralelleştirme ile sorgu yürütücüsü - -- **BaraQL Dil Özellikleri** - - SELECT, INSERT, UPDATE, DELETE - - WHERE, ORDER BY, LIMIT, OFFSET - - GROUP BY, HAVING, toplama fonksiyonları - - INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN - - CTEs (WITH) - - Alt sorgular - - CASE ifadeleri - - UNION, INTERSECT, EXCEPT - -- **Vektör Motoru** - - HNSW indeksi - - IVF-PQ indeksi - - SIMD optimize edilmiş mesafe fonksiyonları - - Nicemleme: skaler 8-bit/4-bit, ürün, ikili - -- **Grafik Motoru** - - Bitişik liste depolaması - - BFS ve DFS geçişi - - Dijkstra en kısa yol - - PageRank - - Louvain topluluk tespiti - - Cypher sorgu ayrıştırıcısı - -- **Tam Metin Arama** - - Ters indeks - - BM25 sıralaması - - TF-IDF - - Fuzzy arama - - Çok dilli tokenizatörler - -- **Protokoller** - - 16 mesaj türüyle Binary wire protocol - - HTTP/REST JSON API - - WebSocket akışı - - Connection pooling - - JWT kimlik doğrulama - - TLS/SSL - -- **Dağıtık Sistemler** - - Raft konsensüs - - Hash, range, consistent-hash parçalama - - Sync/async/semi-sync çoğaltma - - Gossip protokolü - - İki aşamalı commit - -### Performans - -- LSM-Tree: 580K yazma/s, 720K okuma/s -- B-Tree: 1.2M ekleme/s, 1.5M arama/s -- Vector SIMD: 850K kosinüs mesafesi/s (dim=768) - -### Testler - -- 56 test paketinde 262 test -- %100 geçme oranı \ No newline at end of file diff --git a/docs/tr/clients.md b/docs/tr/clients.md deleted file mode 100644 index 8db782c..0000000 --- a/docs/tr/clients.md +++ /dev/null @@ -1,66 +0,0 @@ -# İstemci SDK'ları - -BaraDB JavaScript/TypeScript, Python, Nim ve Rust için resmi istemci kütüphaneleri sağlar. - -## JavaScript / TypeScript - -### Kurulum - -```bash -npm install baradb -``` - -### Temel Kullanım - -```typescript -import { Client } from 'baradb'; - -const client = new Client('localhost', 9472); -await client.connect(); - -const result = await client.query('SELECT name, age FROM users WHERE age > 18'); -``` - -## Python - -### Kurulum - -```bash -pip install baradb -``` - -### Temel Kullanım - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -result = client.query("SELECT name, age FROM users WHERE age > 18") -``` - -## Nim (Gömülü Mod) - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## Rust - -```rust -use baradb::Client; - -let mut client = Client::connect("localhost:9472").await?; -``` - -## HTTP/REST - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` \ No newline at end of file diff --git a/docs/tr/columnar.md b/docs/tr/columnar.md deleted file mode 100644 index af0c80f..0000000 --- a/docs/tr/columnar.md +++ /dev/null @@ -1,50 +0,0 @@ -# Kolonlu Depolama - -Analitik sorgular ve toplama işlemleri için sütun yönlü depolama. - -## Kullanım - -```nim -import barabadb/core/columnar - -var batch = newColumnBatch() -var ageCol = batch.addInt64Col("age") -var nameCol = batch.addStringCol("name") - -ageCol.appendInt64(25) -nameCol.appendString("Alice") -``` - -## Toplamalar - -```nim -echo ageCol.sumInt64() -echo ageCol.avgInt64() -echo ageCol.minInt64() -echo ageCol.maxInt64() -``` - -## Kodlama - -### RLE - -```nim -let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) -``` - -### Dictionary - -```nim -let dict = dictEncode(@["apple", "banana", "apple"]) -``` - -## Sütun Türleri - -| Tip | Açıklama | -|-----|----------| -| `int32` | 32-bit tamsayı | -| `int64` | 64-bit tamsayı | -| `float32` | 32-bit kayan nokta | -| `float64` | 64-bit kayan nokta | -| `string` | Değişken uzunluklu dize | -| `bool` | Mantıksal | \ No newline at end of file diff --git a/docs/tr/configuration.md b/docs/tr/configuration.md deleted file mode 100644 index 7f0ac09..0000000 --- a/docs/tr/configuration.md +++ /dev/null @@ -1,106 +0,0 @@ -# Yapılandırma Referansı - -BaraDB **ortam değişkenleri**, **yapılandırma dosyası** veya **komut satırı bayrakları** ile yapılandırılabilir. - -## Öncelik Sırası - -1. Komut satırı bayrakları (en yüksek) -2. Ortam değişkenleri -3. Yapılandırma dosyası (`baradb.conf` veya `baradb.json`) -4. Yerleşik varsayılanlar (en düşük) - -## Ortam Değişkenleri - -### Ağ - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_ADDRESS` | `127.0.0.1` | Bağlama adresi | -| `BARADB_PORT` | `9472` | TCP ikili protokol portu | -| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API portu | -| `BARADB_WS_PORT` | `9471` | WebSocket portu | - -### Depolama - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_DATA_DIR` | `./data` | Veri dizini yolu | -| `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable boyutu (MB) | -| `BARADB_CACHE_SIZE_MB` | `256` | Sayfa önbellek boyutu (MB) | - -### TLS/SSL - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_TLS_ENABLED` | `false` | TLS'yi etkinleştir | -| `BARADB_CERT_FILE` | — | TLS sertifika dosyası | -| `BARADB_KEY_FILE` | — | TLS özel anahtar dosyası | - -### Güvenlik - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_AUTH_ENABLED` | `false` | Kimlik doğrulamayı etkinleştir | -| `BARADB_JWT_SECRET` | — | JWT imzalama sırrı | -| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | Global istek/saniye | -| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | İstemci başına istek/saniye | - -## Yapılandırma Dosyası - -### baradb.conf - -```ini -[server] -address = "0.0.0.0" -port = 9472 -http_port = 9470 - -[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" - -[auth] -enabled = true -jwt_secret = "change-me-in-production" -``` - -## Komut Satırı Bayrakları - -```bash -./build/baradadb --help -``` - -``` -Options: - -c, --config Yapılandırma dosyası yolu - -p, --port TCP ikili port (varsayılan: 9472) - --http-port HTTP port (varsayılan: 9470) - -d, --data-dir Veri dizini (varsayılan: ./data) - --shell İnteraktif kabuk başlat - --version Versiyonu göster -``` - -## Örnek Yapılandırmalar - -### Geliştirme - -```bash -./build/baradadb --log-level debug --data-dir ./dev_data -``` - -### Üretim Tek Düğüm - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -BARADB_MEMTABLE_SIZE_MB=256 \ -BARADB_CACHE_SIZE_MB=1024 \ -./build/baradadb -``` \ No newline at end of file diff --git a/docs/tr/crossmodal.md b/docs/tr/crossmodal.md deleted file mode 100644 index 8c33110..0000000 --- a/docs/tr/crossmodal.md +++ /dev/null @@ -1,48 +0,0 @@ -# Çapraz Modlu Sorgular - -BaraDB'nin benzersiz yeteneği: birden fazla depolama motorunu tek bir BaraQL ifadesiyle sorgulama. - -## Genel Bakış - -- **Belge/KV** (LSM-Tree) — yapılandırılmış kayıtlar -- **Grafik** (Bitişik Liste) — ilişkiler -- **Vektör** (HNSW/IVF-PQ) — benzerlik araması -- **Tam Metin** (Ters İndeks) — metin araması -- **Kolonlu** — analitik toplamalar - -## Sorgu Kalıpları - -### Vektör + Tam Metin - -```sql -SELECT title FROM articles -WHERE MATCH(body) AGAINST('machine learning') -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; -``` - -### Grafik + Vektör - -```sql -MATCH (u:User)-[:KNOWS]->(friend:User) -WHERE u.name = 'Alice' -ORDER BY cosine_distance(friend.taste_vector, u.taste_vector) -RETURN friend.name; -``` - -## Optimizasyon - -### Çapraz Modlu Sorgu Planlayıcı - -1. En seçici filtre önce -2. Yüklemeleri her motora itin -3. KV aramaları için Bloom filtreleri kullan -4. Bağımsız dalları paralelleştir - -## Performans - -| Sorgu Tipi | Gecikme (10K satır) | -|------------|----------------------| -| FTS + Vector | 15 ms | -| Graph + Vector | 25 ms | -| FTS + Aggregate | 12 ms | \ No newline at end of file diff --git a/docs/tr/deployment.md b/docs/tr/deployment.md deleted file mode 100644 index 3d5bd36..0000000 --- a/docs/tr/deployment.md +++ /dev/null @@ -1,68 +0,0 @@ -# Dağıtım Rehberi - -## Docker - -### Hızlı Başlangıç - -```bash -docker build -t baradb:latest . -docker compose up -d -docker compose ps -``` - -### Docker Compose Dosyaları - -| Dosya | Amaç | -|-------|------| -| `docker-compose.yml` | Geliştirme | -| `docker-compose.prod.yml` | Üretim | - -## Portlar - -| Port | Açıklama | -|------|----------| -| `9472` | İkili tel protokolü | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## Ortam Değişkenleri - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_ADDRESS` | `0.0.0.0` | Dinleme adresi | -| `BARADB_PORT` | `9472` | İkili protokol portu | -| `BARADB_HTTP_PORT` | `9470` | HTTP portu | -| `BARADB_DATA_DIR` | `/data` | Veri dizini | - -## Volumes - -| Yol | Açıklama | -|-----|----------| -| `/data` | Ana veritabanı dizini | -| `/data/server/wal` | Write-ahead log | -| `/data/server/sstables` | SSTable dosyaları | - -## Üretim Kontrol Listesi - -- [ ] TLS sertifikaları oluşturun -- [ ] Güçlü `BARADB_JWT_SECRET` ayarlayın -- [ ] Güvenlik duvarı kurallarını yapılandırın -- [ ] Düzenli yedeklemeler ayarlayın -- [ ] Kaynak sınırlarını kontrol edin -- [ ] İzlemeyi yapılandırın - -## TLS Docker'da - -```bash -mkdir -p certs -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout certs/server.key -out certs/server.crt -``` - -## Yedekleme Docker'da - -```bash -docker exec baradb /app/backup backup --data-dir=/data -docker exec baradb /app/backup list -docker exec baradb /app/backup restore --input=backup_xxx.tar.gz -``` \ No newline at end of file diff --git a/docs/tr/distributed.md b/docs/tr/distributed.md deleted file mode 100644 index b7ead1d..0000000 --- a/docs/tr/distributed.md +++ /dev/null @@ -1,73 +0,0 @@ -# Dağıtık Sistemler - -BaraDB Raft konsensüsü, parçalama ve çoğaltma ile dağıtık dağıtımı destekler. - -## Raft Konsensüs - -Lider seçimi ve log çoğaltma: - -```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() -``` - -## Parçalama - -```nim -import barabadb/core/sharding - -var router = newShardRouter(ShardConfig( - numShards: 4, - replicas: 2, - strategy: ssHash -)) -``` - -### Parçalama Stratejileri - -| Strateji | Açıklama | -|----------|----------| -| `ssHash` | Hash tabanlı parçalama | -| `ssRange` | Aralık tabanlı parçalama | -| `ssConsistent` | Tutarlı hashleme | - -## Çoğaltma - -```nim -import barabadb/core/replication - -var rm = newReplicationManager(rmSync) -rm.addReplica(newReplica("r1", "10.0.0.1", 9472)) -``` - -### Çoğaltma Modları - -| Mod | Açıklama | -|-----|----------| -| `rmSync` | Senkron çoğaltma | -| `rmAsync` | Asenkron çoğaltma | -| `rmSemiSync` | Yarı-senkron çoğaltma | - -## Dağıtık İşlemler - -İki aşamalı commit: - -```nim -import barabadb/core/disttxn - -var dt = newDistributedTxn() -dt.prepare(@["node1", "node2"]) -dt.commit() -``` - -## Resmi Doğrulama - -Temel dağıtık algoritmalar TLA+'da belirtilmiş ve model kontrolü yapılmıştır. \ No newline at end of file diff --git a/docs/tr/docker.md b/docs/tr/docker.md deleted file mode 100644 index 5076de0..0000000 --- a/docs/tr/docker.md +++ /dev/null @@ -1,78 +0,0 @@ -# Docker Dağıtım Rehberi - -## Hızlı Başlangıç - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB - -docker build -t baradb:latest . - -docker compose up -d - -docker compose ps -docker compose logs -f -``` - -## Dosyalar - -| Dosya | Açıklama | -|-------|----------| -| `Dockerfile` | Multi-stage üretim build | -| `docker-compose.yml` | Geliştirme yapılandırması | -| `docker-compose.prod.yml` | Üretim yapılandırması | - -## Image Oluşturma - -```bash -docker build -t baradb:latest . -``` - -## Çalıştırma - -### Geliştirme - -```bash -docker compose up -d -docker compose down -``` - -### Üretim - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -## Portlar - -| Port | Açıklama | -|------|----------| -| `9472` | İkili tel protokolü | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## Ortam Değişkenleri - -| Değişken | Varsayılan | Açıklama | -|----------|------------|----------| -| `BARADB_ADDRESS` | `0.0.0.0` | Dinleme adresi | -| `BARADB_PORT` | `9472` | İkili protokol portu | -| `BARADB_HTTP_PORT` | `9470` | HTTP portu | -| `BARADB_DATA_DIR` | `/data` | Veri dizini | - -## Volumes - -| Yol | Açıklama | -|-----|----------| -| `/data` | Ana veri dizini | -| `/data/server/wal` | Write-ahead log | -| `/data/server/sstables` | SSTable dosyaları | - -## Üretim Kontrol Listesi - -- [ ] `./certs/` içinde TLS sertifikaları oluşturun -- [ ] Güçlü `BARADB_JWT_SECRET` ayarlayın -- [ ] Güvenlik duvarı kurallarını yapılandırın -- [ ] Düzenli yedeklemeler yapılandırın -- [ ] Kaynak sınırlarını kontrol edin -- [ ] İzleme ayarlayın \ No newline at end of file diff --git a/docs/tr/fts.md b/docs/tr/fts.md deleted file mode 100644 index 0213b10..0000000 --- a/docs/tr/fts.md +++ /dev/null @@ -1,47 +0,0 @@ -# Tam Metin Arama Motoru - -BM25 ve TF-IDF sıralamasıyla ters indeks. - -## Kullanım - -```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") - -let results = idx.search("programming language") -let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) -``` - -## Sıralama Yöntemleri - -### BM25 - -```nim -let bm25 = idx.searchBM25("query terms") -``` - -### TF-IDF - -```nim -let tfidf = idx.searchTfidf("query terms") -``` - -## Arama Özellikleri - -| Özellik | Açıklama | -|----------|----------| -| Fuzzy search | Levenshtein mesafesi toleransı | -| Wildcard | Önek, sonek ve ara joker | -| Regex | Normal ifade kalıpları | -| Phrase search | Tam ifade eşleme | -| Boolean | AND, OR, NOT operatörleri | - -## SQL Arayüzü - -```sql -CREATE INDEX idx_fts ON articles(body) USING FTS; -SELECT * FROM articles WHERE body @@ 'machine learning'; -``` \ No newline at end of file diff --git a/docs/tr/graph.md b/docs/tr/graph.md deleted file mode 100644 index db2342c..0000000 --- a/docs/tr/graph.md +++ /dev/null @@ -1,42 +0,0 @@ -# Grafik Motoru - -Grafik geçişi ve analizi için yerleşik algoritmalarla bitişik liste depolaması. - -## Kullanım - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -``` - -## Algoritmalar - -| Algoritma | Açıklama | -|-----------|----------| -| `bfs` | Enine arama | -| `dfs` | Derine arama | -| `dijkstra` | En kısa ağırlıklı yol | -| `pageRank` | Düğüm önem sıralaması | -| `louvain` | Topluluk tespiti | -| `patternMatch` | Altgraf eşleme | - -## Cypher Sorgusu - -```nim -import barabadb/graph/cypher - -var engine = newCypherEngine(g) -let results = engine.execute(""" - MATCH (p:Person)-[:KNOWS]->(friend:Person) - WHERE p.name = 'Alice' - RETURN friend.name -""") -``` \ No newline at end of file diff --git a/docs/tr/index.md b/docs/tr/index.md deleted file mode 100644 index 759d198..0000000 --- a/docs/tr/index.md +++ /dev/null @@ -1,59 +0,0 @@ -# BaraDB Dokümantasyonu (Türkçe) - -**Nim ile yazılmış çok modlu bir veritabanı motoru — %100 native, sıfır bağımlılık.** - -## Hızlı Bağlantılar - -> **Not:** Türkçe dokümantasyon geliştirme aşamasındadır. Tam bilgi için [İngilizce sürüme](../en/) bakın. - -### Başlangıç -- [Kurulum](../en/installation.md) -- [Hızlı Başlangıç](../en/quickstart.md) -- [Mimari Genel Bakış](../en/architecture.md) -- [Yapılandırma Referansı](../en/configuration.md) -- [Dağıtım Rehberi](../en/deployment.md) - -### Temel Kavramlar -- [BaraQL Sorgu Dili](../en/baraql.md) -- [Depolama Motorları](../en/storage.md) -- [Şema Sistemi](../en/schema.md) -- [Çapraz Modlu Sorgular](../en/crossmodal.md) - -### Motorlar -- [LSM-Tree Depolama](../en/lsm.md) -- [B-Tree İndeksi](../en/btree.md) -- [Vektör Arama](../en/vector.md) -- [Grafik Motoru](../en/graph.md) -- [Tam Metin Arama](../en/fts.md) -- [Kolonlu Depolama](../en/columnar.md) - -### API ve İstemciler -- [İstemci SDK'ları](../en/clients.md) -- [İkili Protokol](../en/api-binary.md) -- [HTTP/REST API](../en/api-http.md) -- [WebSocket API](../en/api-websocket.md) -- [Protokol Referansı](../en/protocol.md) - -### Operasyonlar -- [Performans ve Kıyaslama](../en/performance.md) -- [Güvenlik Rehberi](../en/security.md) -- [İzleme ve Gözlemlenebilirlik](../en/monitoring.md) -- [Yedekleme ve Kurtarma](../en/backup.md) -- [Sorun Giderme](../en/troubleshooting.md) - -### İleri Düzey -- [İşlemler ve MVCC](../en/transactions.md) -- [Dağıtık Sistemler](../en/distributed.md) -- [Kullanıcı Tanımlı Fonksiyonlar](../en/udf.md) - ---- - -## Proje Bilgileri - -- [Değişiklik Günlüğü](../en/changelog.md) -- [Lisans](../../LICENSE) -- [GitHub Deposu](https://github.com/katehonz/barabaDB) - ---- - -*Türkçe dokümantasyon çeviri aşamasındadır.* \ No newline at end of file diff --git a/docs/tr/installation.md b/docs/tr/installation.md deleted file mode 100644 index 4c65084..0000000 --- a/docs/tr/installation.md +++ /dev/null @@ -1,308 +0,0 @@ -# BaraDB - Kurulum Rehberi - -## Gereksinimler - -- **Nim Derleyici** >= 2.2.0 -- **OpenSSL** geliştirme başlıkları (TLS desteği için) -- **İşletim Sistemi**: Linux, macOS, Windows - -### Desteklenen Platformlar - -| OS | Mimari | Durum | -|----|--------|-------| -| Linux | x86_64 | ✅ Tam destek | -| Linux | ARM64 | ✅ Tam destek | -| macOS | x86_64 | ✅ Tam destek | -| macOS | ARM64 (Apple Silicon) | ✅ Tam destek | -| Windows | x86_64 | ✅ Destekleniyor | -| FreeBSD | x86_64 | 🟡 Topluluk testli | - -## Nim Kurulumu - -### Linux - -```bash -# Resmi kurulum scripti -curl https://nim-lang.org/choosenim/init.sh -sSf | sh - -# Ubuntu/Debian -sudo apt-get update -sudo apt-get install nim - -# Fedora -sudo dnf install nim - -# Arch Linux -sudo pacman -S nim -``` - -### macOS - -```bash -# Homebrew -brew install nim - -# MacPorts -sudo port install nim -``` - -### Windows - -```powershell -# choosenim ile -curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell - - -# winget ile -winget install nim - -# scoop ile -scoop install nim -``` - -### Kurulumu Doğrulama - -```bash -nim --version -# Beklenen: Nim Compiler Version 2.2.0 veya daha yeni -``` - -## OpenSSL Kurulumu - -### Linux - -```bash -# Ubuntu/Debian -sudo apt-get install libssl-dev - -# Fedora -sudo dnf install openssl-devel - -# Arch Linux -sudo pacman -S openssl -``` - -### macOS - -OpenSSL sistemle birlikte gelir. Gerekirse: - -```bash -brew install openssl -``` - -### Windows - -OpenSSL, Nim Windows dağıtımıyla birlikte gelir. Manuel derlemeler için [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) adresinden indirin. - -## BaraDB Derleme - -### Depoyu Klonlama - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB -``` - -### Bağımlılıkları Kurma - -```bash -nimble install -d -y -``` - -### Derleme Seçenekleri - -#### Debug Derleme - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -#### Release Derleme (Önerilen) - -```bash -nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim -``` - -#### Nimble Tasks Kullanma - -```bash -# Debug derleme -nimble build_debug - -# Release derleme -nimble build_release -``` - -#### Binary Boyutunu Küçültme - -```bash -nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim -strip build/baradadb -``` - -### Derlemeyi Doğrulama - -```bash -./build/baradadb --version -# Beklenen: BaraDB v1.1.6 — Multimodal Database Engine -``` - -## Testleri Çalıştırma - -### Tüm Testler - -```bash -nim c -d:ssl -r tests/test_all.nim -``` - -### Belirli Test Süitleri - -```bash -# Depolama testleri -nim c -d:ssl -r tests/test_storage.nim - -# Sorgu motoru testleri -nim c -d:ssl -r tests/test_query.nim - -# Protokol testleri -nim c -d:ssl -r tests/test_protocol.nim -``` - -### Benchmarklar - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## Kurulum Seçenekleri - -### Sistem Geneli Kurulum - -```bash -# Release binary derle -nimble build_release - -# /usr/local/bin'e kur -sudo cp build/baradadb /usr/local/bin/ -sudo chmod +x /usr/local/bin/baradadb - -# Veri dizini oluştur -sudo mkdir -p /var/lib/baradb -sudo chmod 755 /var/lib/baradb -``` - -### Ön Derlenmiş Binary - -En son sürümü platformunuz için indirin: - -```bash -# Linux x86_64 -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 - -# Linux ARM64 -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64 -chmod +x baradadb-linux-arm64 -mv baradadb-linux-arm64 /usr/local/bin/baradadb - -# macOS -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64 -chmod +x baradadb-darwin-amd64 -mv baradadb-darwin-amd64 /usr/local/bin/baradadb -``` - -### Docker - -```bash -# Resmi image'i çek -docker pull barabadb/barabadb:latest - -# Çalıştır -docker run -d \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - barabadb/barabadb -``` - -### Docker Compose - -```bash -docker-compose up -d -``` - -### Gömülü Kullanım (Nim Projeleri) - -`.nimble` dosyanıza ekleyin: - -```nim -requires "barabadb >= 1.1.6" -``` - -Kodunuzda kullanın: - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## İlk Çalıştırma - -```bash -# Sunucuyu başlat -./build/baradadb - -# Beklenen çıktı: -# BaraDB v1.1.6 — Multimodal Database Engine -# BaraDB TCP listening on 127.0.0.1:9472 - -# HTTP API ile test et -curl http://localhost:9470/health - -# İnteraktif shell -./build/baradadb --shell -``` - -## Kurulum Sorunlarını Giderme - -### "cannot open file: hunos" - -```bash -nimble install -d -y -``` - -### "BaraDB requires SSL support" - -Her zaman `-d:ssl` ile derleyin: - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -### Yavaş derleme - -Paralel derleme kullanın: - -```bash -nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim -``` - -### Büyük binary boyutu - -Boyut optimizasyonu kullanın: - -```bash -nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim -``` - -## Sonraki Adımlar - -- [Hızlı Başlangıç](quickstart.md) -- [Yapılandırma Referansı](configuration.md) -- [Mimari Genel Bakış](architecture.md) -- [BaraQL Sorgu Dili](baraql.md) \ No newline at end of file diff --git a/docs/tr/lsm.md b/docs/tr/lsm.md deleted file mode 100644 index d9e782b..0000000 --- a/docs/tr/lsm.md +++ /dev/null @@ -1,48 +0,0 @@ -# LSM-Tree Depolama Motoru - -Log-Structured Merge-Tree mimarisini kullanan BaraDB'deki birincil depolama motoru. - -## Mimari - -``` -┌─────────────────────────────────────────────┐ -│ Writes │ -│ (append to WAL + MemTable) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ MemTable │ -│ (in-memory sorted buffer) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ SSTable │ -│ (sorted string table on disk) │ -└─────────────────────────────────────────────┘ -``` - -## Kullanım - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") - -db.put("key1", cast[seq[byte]]("value1")) - -let (found, value) = db.get("key1") - -db.delete("key1") - -db.close() -``` - -## Özellikler - -- **Yazma için optimize**: Append-only log yapısı -- **Dayanıklılık**: WAL çökme kurtarma sağlar -- **Bloom Filter**: Hızlı negatif aramalar -- **Compaction**: Boyut katmanlı strateji -- **Page Cache**: Sık erişilen sayfalar için LRU önbellek \ No newline at end of file diff --git a/docs/tr/mcp.md b/docs/tr/mcp.md deleted file mode 100644 index c4f934c..0000000 --- a/docs/tr/mcp.md +++ /dev/null @@ -1,109 +0,0 @@ -# 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/tr/monitoring.md b/docs/tr/monitoring.md deleted file mode 100644 index 1598b10..0000000 --- a/docs/tr/monitoring.md +++ /dev/null @@ -1,84 +0,0 @@ -# İzleme ve Gözlemlenebilirlik - -## Sağlık Kontrolleri - -### HTTP Sağlık Endpoint'i - -```bash -curl http://localhost:9470/health -``` - -Yanıt: - -```json -{ - "status": "healthy", - "version": "0.1.0", - "uptime_seconds": 86400, - "checks": { - "storage": "ok", - "memory": "ok", - "connections": "ok" - } -} -``` - -## Metrikler - -### Prometheus Uyumlu Metrikler - -```bash -curl http://localhost:9470/metrics -``` - -Örnek çıktı: - -``` -baradb_queries_total 152340 -baradb_queries_duration_seconds_bucket{le="0.001"} 45000 -baradb_storage_lsm_size_bytes 2147483648 -baradb_cache_hit_rate 0.94 -baradb_active_connections 42 -``` - -## Günlükleme - -### Günlük Seviyeleri - -| Seviye | Açıklama | -|--------|----------| -| `debug` | Detaylı dahili operasyonlar | -| `info` | Normal operasyonlar | -| `warn` | Kurtarılabilir sorunlar | -| `error` | Dikkat gerektiren başarısızlıklar | - -### Yapılandırılmış JSON Günlükleri - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/baradb.log \ -./build/baradadb -``` - -## Grafana Dashboard - -Dashboard ID `baradb-001` içe aktarın veya `monitoring/grafana-dashboard.json` içindeki JSON'u kullanın. - -Temel paneller: -- Saniyedeki sorgular -- Sorgu gecikme yüzdeleri (p50, p95, p99) -- Depolama boyutu ve SSTable sayısı -- Önbellek isabet oranı -- Aktif bağlantılar -- İşlem oranı -- Hata oranı - -## Metriklerle Sorun Giderme - -| Belirti | Metrik | Eylem | -|---------|--------|-------| -| Yavaş sorgular | `baradb_queries_duration_seconds` | Önbellek isabet oranını kontrol edin, indeks ekleyin | -| Yüksek bellek | `process_resident_memory_bytes` | Memtable/cache boyutlarını azaltın | -| Depolama büyüyor | `baradb_storage_lsm_size_bytes` | Manuel sıkıştırma çalıştırın | -| Bağlantı hataları | `baradb_active_connections` | Bağlantı havuzunu artırın veya düğüm ekleyin | \ No newline at end of file diff --git a/docs/tr/performance.md b/docs/tr/performance.md deleted file mode 100644 index 46a3fbd..0000000 --- a/docs/tr/performance.md +++ /dev/null @@ -1,68 +0,0 @@ -# Performans Rehberi - -## Kıyaslama Metodolojisi - -Tüm kıyaslamalar şununla çalıştırılır: -- **Derleyici**: Nim 2.2.0 `-d:release --opt:speed` -- **CPU**: AMD Ryzen 9 5900X (12 çekirdek / 24 iş parçacığı) -- **Bellek**: 64 GB DDR4-3600 -- **Depolama**: Samsung 980 Pro NVMe SSD - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## Depolama Motoru Kıyaslamaları - -### LSM-Tree - -| Metrik | Değer | -|--------|-------| -| Yazma verimi | ~580,000 ops/s | -| Okuma verimi | ~720,000 ops/s | -| Ortalama yazma gecikmesi | 1.7 µs | -| Ortalama okuma gecikmesi | 1.4 µs | - -### B-Tree İndeksi - -| Metrik | Değer | -|--------|-------| -| Ekleme verimi | ~1,200,000 ops/s | -| Nokta arama verimi | ~1,500,000 ops/s | - -## Vektör Motoru Kıyaslamaları - -### HNSW İndeksi - -| Metrik | Değer | -|--------|-------| -| Ekleme (dim=128) | ~45,000 vectors/s | -| Top-10 arama (n=100K) | ~8 ms | - -Parametreler: `M=16`, `efConstruction=200`, `efSearch=64`. - -## Ayar Kılavuzu - -### Yoğun Yazma İş Yükü - -```bash -BARADB_MEMTABLE_SIZE_MB=256 -BARADB_WAL_SYNC_INTERVAL_MS=10 -BARADB_COMPACTION_INTERVAL_MS=30000 -``` - -### Yoğun Okuma İş Yükü - -```bash -BARADB_CACHE_SIZE_MB=1024 -BARADB_BLOOM_BITS_PER_KEY=10 -BARADB_COMPACTION_INTERVAL_MS=120000 -``` - -### Vektör Arama - -```bash -BARADB_VECTOR_EF_CONSTRUCTION=200 -BARADB_VECTOR_EF_SEARCH=128 -BARADB_VECTOR_M=32 -``` \ No newline at end of file diff --git a/docs/tr/protocol.md b/docs/tr/protocol.md deleted file mode 100644 index ffd928a..0000000 --- a/docs/tr/protocol.md +++ /dev/null @@ -1,67 +0,0 @@ -# Protokol Referansı - -BaraDB istemci iletişimi için birden fazla protokol destekler: -- **Binary Wire Protocol** — yüksek performanslı, düşük gecikme -- **HTTP/REST API** — dil agnostik, kolay hata ayıklama -- **WebSocket** — akış ve pub/sub - -## Binary Wire Protocol - -Tüm çok baytlı değerler için big-endian kodlama kullanır. - -### Bağlantı Döngüsü - -``` -Client Server - | | - |─── TCP connect ──────────────>| - |─── Auth message ─────────────>| - |<── Auth_OK / Error ───────────| - |─── Query message ────────────>| - |<── Data / Complete / Error ───| -``` - -### Mesaj Formatı - -``` -┌─────────────┬─────────────┬─────────────┬─────────────────────┐ -│ Length │ Type │ Sequence │ Payload │ -│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ -└─────────────┴─────────────┴─────────────┴─────────────────────┘ -``` - -### Mesaj Türleri - -| Tip | ID | Açıklama | -|-----|----|----------| -| Query | 0x01 | Sorgu çalıştır | -| Insert | 0x02 | Veri ekle | -| Update | 0x03 | Veri güncelle | -| Delete | 0x04 | Veri sil | -| Ready | 0x05 | Sonraki komut için hazır | -| Error | 0x06 | Hata yanıtı | - -## HTTP/REST API - -Base URL: `http://localhost:9470/api/v1` - -### Uç Noktalar - -#### Health - -```http -GET /health -``` - -#### Sorgu - -```http -POST /query -{ - "query": "SELECT * FROM users" -} -``` - -## WebSocket Protocol - -URL: `ws://localhost:9471` \ No newline at end of file diff --git a/docs/tr/quickstart.md b/docs/tr/quickstart.md deleted file mode 100644 index ffbdc7d..0000000 --- a/docs/tr/quickstart.md +++ /dev/null @@ -1,99 +0,0 @@ -# BaraDB - Hızlı Başlangıç Rehberi - -## Sunucuyu Başlatma - -```bash -./build/baradadb -``` - -Sunucu varsayılan olarak `localhost:9470` üzerinde başlar. - -## CLI ile Bağlanma - -```bash -./build/baradadb --shell -``` - -## Temel İşlemler - -### Şema Oluşturma - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; -``` - -### Veri Ekleme - -```sql -INSERT Person { name := 'Alice', age := 30 }; -``` - -### Veri Sorgulama - -```sql -SELECT name, age FROM Person WHERE age > 18; -``` - -### Veri Güncelleme - -```sql -UPDATE Person SET age = 31 WHERE name = 'Alice'; -``` - -### Veri Silme - -```sql -DELETE FROM Person WHERE name = 'Bob'; -``` - -## Gelişmiş Sorgular - -### JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -### CTE - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## Vektör Arama - -```sql -INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] }; -SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10; -``` - -## Grafik Operasyonları - -```sql -MATCH (p:Person)-[:KNOWS]->(other:Person) -WHERE p.name = 'Alice' -RETURN other.name; -``` - -## HTTP/REST API - -```bash -curl http://localhost:9470/api/users -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 30}' -``` - -## Sonraki Adımlar - -- [BaraQL Referans](baraql.md) -- [Depolama Motorları](storage.md) -- [Mimari Genel Bakış](architecture.md) \ No newline at end of file diff --git a/docs/tr/schema.md b/docs/tr/schema.md deleted file mode 100644 index 118a507..0000000 --- a/docs/tr/schema.md +++ /dev/null @@ -1,46 +0,0 @@ -# Şema Sistemi - -BaraDB tip mirası ve otomatik geçişlerle schema-first tasarımı kullanır. - -## Tipleri Tanımlama - -```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) -``` - -## Tip Mirası - -```nim -let employee = newType("Employee") -employee.setBases(@["Person"]) -employee.addProperty("department", "str") -s.addType("default", employee) -``` - -## Şema İşlemleri - -### Diff - -```nim -let diff = s.diff(oldSchema, newSchema) -``` - -## Özellik Tipleri - -| Tip | Açıklama | -|-----|----------| -| `str` | Dize | -| `int32` | 32-bit tamsayı | -| `int64` | 64-bit tamsayı | -| `float32` | 32-bit kayan nokta | -| `float64` | 64-bit kayan nokta | -| `bool` | Mantıksal | -| `datetime` | Tarih/zaman | -| `bytes` | İkili veri | \ No newline at end of file diff --git a/docs/tr/security.md b/docs/tr/security.md deleted file mode 100644 index 83d3205..0000000 --- a/docs/tr/security.md +++ /dev/null @@ -1,76 +0,0 @@ -# Güvenlik Rehberi - -## TLS/SSL Şifreleme - -BaraDB tüm protokoller için TLS 1.3 destekler. Sertifika sağlanmazsa, sunucu sıfır yapılandırma şifrelemesi için başlangıçta otomatik olarak kendinden imzalı sertifika üretir. - -### Özel Sertifika Kullanımı - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_CERT_FILE=/etc/baradb/server.crt \ -BARADB_KEY_FILE=/etc/baradb/server.key \ -./build/baradadb -``` - -### Kendinden İmzalı Sertifika Oluşturma - -```bash -openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ - -days 365 -nodes -subj "/CN=localhost" -``` - -## Kimlik Doğrulama - -### JWT Tabanlı Kimlik Doğrulama - -BaraDB HMAC-SHA256 imzalı JWT kullanır. - -### Kimlik Doğrulamayı Etkinleştirme - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -### Rol Tabanlı Erişim Kontrolü - -| Rol | İzinler | -|-----|---------| -| `admin` | Tam erişim | -| `write` | Okuma + Yazma | -| `read` | Salt okunur | -| `monitor` | Yalnızca metrikler ve sağlık | - -## Hız Sınırlama - -Token-bucket hız sınırlama kötüye kullanımı önler: - -```nim -var rl = newRateLimiter( - rlaTokenBucket, - globalRate = 10000, - perClientRate = 1000, - burstSize = 100 -) -``` - -## Ağ Güvenliği - -### Bağlama Adresi - -```bash -BARADB_ADDRESS=0.0.0.0 ./build/baradadb -``` - -## Güvenlik Kontrol Listesi - -- [ ] Varsayılan JWT sırrını değiştirin -- [ ] Geçerli sertifikalarla TLS'yi etkinleştirin -- [ ] Belirli arayüzlere bağlayın -- [ ] Üretimde kimlik doğrulamayı etkinleştirin -- [ ] Hız sınırlama yapılandırın -- [ ] Denetim günlüğünü etkinleştirin -- [ ] Durağan verileri şifreleyin (LUKS veya uygulama düzeyinde) -- [ ] BaraDB'yi root olmayan kullanıcı olarak çalıştırın \ No newline at end of file diff --git a/docs/tr/storage.md b/docs/tr/storage.md deleted file mode 100644 index 916d53f..0000000 --- a/docs/tr/storage.md +++ /dev/null @@ -1,67 +0,0 @@ -# Depolama Motorları - -BaraDB farklı erişim kalıpları için optimize edilmiş birden fazla depolama motoru sağlar. - -## LSM-Tree (Anahtar-Değer) - -Yazma için optimize edilmiş append-only log yapılı birincil depolama motoru. - -### Kullanım - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key1", cast[seq[byte]]("value1")) -let (found, value) = db.get("key1") -db.close() -``` - -### Bileşenler - -- **MemTable**: Bellek içi sıralı tampon -- **WAL**: Dayanıklılık için write-ahead log -- **SSTable**: Disk üzerinde sıralı string tabloları -- **Bloom Filter**: Hızlı negatif aramalar için olasılıksal yapı -- **Compaction**: Seviye yönetimi ile boyut katmanlı strateji -- **Page Cache**: Hit oranı izlemeli LRU önbellek - -## B-Tree İndeksi - -Aralık taramaları ve nokta aramaları için sıralı indeks. - -### Kullanım - -```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) - -Yazma işlemlerinin dayanıklılığını sağlar. - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append("txn1", "SET key1 value1") -wal.flush() -``` - -## Bloom Filter - -Hızlı negatif aramalar için olasılıksal veri yapısı. - -```nim -import barabadb/storage/bloom - -var filter = newBloomFilter(10000, 0.01) -filter.add("key1") -if filter.mightContain("key1"): - echo "muhtemelen var" -``` \ No newline at end of file diff --git a/docs/tr/transactions.md b/docs/tr/transactions.md deleted file mode 100644 index 37eb176..0000000 --- a/docs/tr/transactions.md +++ /dev/null @@ -1,47 +0,0 @@ -# İşlemler ve MVCC - -MVCC (Multi-Version Concurrency Control), snapshot izolasyonu ve deadlock algılama ile. - -## Kullanım - -```nim -import barabadb/core/mvcc - -var tm = newTxnManager() -let txn = tm.beginTxn() - -discard tm.write(txn, "key1", cast[seq[byte]]("value1")) -discard tm.write(txn, "key2", cast[seq[byte]]("value2")) - -tm.savepoint(txn) -discard tm.write(txn, "key3", cast[seq[byte]]("value3")) -discard tm.rollbackToSavepoint(txn) - -discard tm.commit(txn) -``` - -## İşlem İzolasyonu - -BaraDB **snapshot izolasyonu** kullanır: -- Okuyucular yazıcıları engellemez -- Yazıcılar okuyucuları engellemez -- Her işlem tutarlı bir snapshot görür - -## Deadlock Algılama - -```nim -import barabadb/core/deadlock - -var detector = newDeadlockDetector() -if detector.detectCycle(txn1, txn2): - echo "Deadlock algılandı!" -``` - -## Resmi Doğrulama - -MVCC/Snapshot Isolation protokolü TLA+'da resmi olarak belirtilmiştir: - -```bash -cd formal-verification -java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla -``` \ No newline at end of file diff --git a/docs/tr/troubleshooting.md b/docs/tr/troubleshooting.md deleted file mode 100644 index da48c29..0000000 --- a/docs/tr/troubleshooting.md +++ /dev/null @@ -1,81 +0,0 @@ -# Sorun Giderme Rehberi - -## Kurulum Sorunları - -### Nim Bulunamadı - -```bash -curl https://nim-lang.org/choosenim/init.sh -sSf | sh -``` - -### SSL Derleme Hatası - -```bash -nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim -``` - -### Eksik Bağımlılıklar - -```bash -nimble install -d -y -``` - -## Çalışma Zamanı Sorunları - -### Port Zaten Kullanımda - -```bash -BARADB_PORT=5433 ./build/baradadb -``` - -### İzin Reddedildi - -```bash -mkdir -p ./data -chmod 755 ./data -``` - -### Yetersiz Bellek - -```bash -BARADB_MEMTABLE_SIZE_MB=32 \ -BARADB_CACHE_SIZE_MB=128 \ -./build/baradadb -``` - -## Sorgu Sorunları - -### Sözdizimi Hatası - -```sql -SELECT name, age FROM users WHERE age > 18; -``` - -### Tablo Bulunamadı - -```sql -CREATE TYPE User { name: str, age: int32 }; -``` - -## Bağlantı Sorunları - -### Bağlantı Reddedildi - -```bash -./build/baradadb -sudo ufw allow 9472 -``` - -## Performans Sorunları - -### Yavaş Sorgular - -1. İndeks ekleyin: `CREATE INDEX idx_users_name ON users(name);` -2. LIMIT kullanın -3. Önbelleği artırın: `BARADB_CACHE_SIZE_MB=1024` - -## Hata Ayıklama Modu - -```bash -BARADB_LOG_LEVEL=debug ./build/baradadb -``` \ No newline at end of file diff --git a/docs/tr/udf.md b/docs/tr/udf.md deleted file mode 100644 index 7442a1d..0000000 --- a/docs/tr/udf.md +++ /dev/null @@ -1,47 +0,0 @@ -# Kullanıcı Tanımlı Fonksiyonlar - -BaraQL'i özel fonksiyonlarla genişlet. - -## Kullanım - -```nim -import barabadb/query/udf - -var reg = newUDFRegistry() - -reg.registerStdlib() - -reg.register("greet", @[UDFParam(name: "name", typeName: "str")], - "str", proc(args: seq[Value]): Value = - return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) -``` - -## Standart Kütüphane Fonksiyonları - -| Fonksiyon | Açıklama | Örnek | -|-----------|----------|-------| -| `abs(n)` | Mutlak değer | `abs(-5)` → 5 | -| `sqrt(n)` | Karekök | `sqrt(16)` → 4 | -| `pow(n, e)` | Üs | `pow(2, 3)` → 8 | -| `lower(s)` | Küçük harf | `lower('ABC')` → 'abc' | -| `upper(s)` | Büyük harf | `upper('abc')` → 'ABC' | -| `len(s)` | Uzunluk | `len('hello')` → 5 | -| `trim(s)` | Boşluk kırpma | `trim(' hello ')` → 'hello' | - -## Fonksiyon Kaydetme - -```nim -reg.register( - name: "my_function", - params: @[UDFParam(name: "arg1", typeName: "str")], - returnType: "str", - body: proc(args: seq[Value]): Value = - result = Value(kind: vkString, strVal: "") -) -``` - -## Sorgularda UDF Kullanımı - -```sql -SELECT greet(name) FROM users; -``` \ No newline at end of file diff --git a/docs/tr/vector.md b/docs/tr/vector.md deleted file mode 100644 index 7f4b82c..0000000 --- a/docs/tr/vector.md +++ /dev/null @@ -1,65 +0,0 @@ -# Vektör Arama Motoru - -Benzerlik araması için HNSW ve IVF-PQ indeksleri. - -## Kullanım - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) -``` - -## İndeks Türleri - -### HNSW - -Hiyerarşik Navigable Small World grafiği. - -```nim -var hnsw = newHNSWIndex( - dimensions = 128, - m = 16, - efConstruction = 200, - efSearch = 100 -) -``` - -### IVF-PQ - -Ürün nicemleme ile Ters Dosya İndeksi. - -```nim -var ivfpq = newIVFPQIndex( - dimensions = 128, - numCentroids = 256, - subQuantizers = 8 -) -``` - -## Mesafe Metrikleri - -| Metrik | Açıklama | -|--------|----------| -| `cosine` | Kosinüs benzerliği | -| `euclidean` | L2 mesafesi | -| `dotproduct` | Nokta çarpımı | -| `manhattan` | L1 mesafesi | - -## Nicemleme - -```nim -let scalar = scalarQuantize(data, bits = 8) -let pq = productQuantize(data, subVectors = 8, bits = 8) -``` - -## SIMD Hızlandırma - -```nim -import barabadb/vector/simd - -let dist = simdCosineDistance(vec1, vec2) -``` \ No newline at end of file diff --git a/docs/zh/api-binary.md b/docs/zh/api-binary.md deleted file mode 100644 index 5ca960b..0000000 --- a/docs/zh/api-binary.md +++ /dev/null @@ -1,62 +0,0 @@ -# 二进制协议 API - -用于高性能客户端连接的低级 wire 协议。 - -## 消息格式 - -所有消息使用大端字节序： - -``` -┌────────┬────────┬────────┬────────┬─────────────┐ -│ Length │ Type │ Seq │ Status │ Payload │ -│ 4 bytes│ 1 byte │ 2 bytes│ 1 byte │ N bytes │ -└────────┴────────┴────────┴────────┴─────────────┘ -``` - -## 消息类型 - -### 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) -``` - -## 响应码 - -| 代码 | 名称 | 描述 | -|------|------|------| -| 0x00 | OK | 成功 | -| 0x01 | ERROR | 一般错误 | -| 0x02 | AUTH_REQUIRED | 需要认证 | -| 0x03 | INVALID_QUERY | 查询语法错误 | -| 0x04 | NOT_FOUND | 资源未找到 | \ No newline at end of file diff --git a/docs/zh/api-http.md b/docs/zh/api-http.md deleted file mode 100644 index 2dbfa54..0000000 --- a/docs/zh/api-http.md +++ /dev/null @@ -1,62 +0,0 @@ -# HTTP/REST API - -用于 Web 应用程序的基于 JSON 的 REST API。 - -## Base URL - -``` -http://localhost:9470/api -``` - -## 端点 - -### GET /api/users - -列出所有用户： - -```bash -curl http://localhost:9470/api/users -``` - -### GET /api/users/:id - -按 ID 获取用户： - -```bash -curl http://localhost:9470/api/users/1 -``` - -### POST /api/users - -创建用户： - -```bash -curl -X POST http://localhost:9470/api/users \ - -d '{"name": "Charlie", "age": 35}' -``` - -### PUT /api/users/:id - -更新用户： - -```bash -curl -X PUT http://localhost:9470/api/users/1 \ - -d '{"name": "Alice", "age": 31}' -``` - -### DELETE /api/users/:id - -删除用户： - -```bash -curl -X DELETE http://localhost:9470/api/users/1 -``` - -## 查询端点 - -通过 HTTP 执行 BaraQL 查询： - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"sql": "SELECT * FROM users WHERE age > 18"}' -``` \ No newline at end of file diff --git a/docs/zh/api-websocket.md b/docs/zh/api-websocket.md deleted file mode 100644 index fb83299..0000000 --- a/docs/zh/api-websocket.md +++ /dev/null @@ -1,67 +0,0 @@ -# WebSocket API - -用于实时数据流和推送通知的全双工流。 - -## 连接 - -``` -ws://localhost:9471/ws -``` - -## 客户端示例 - -```javascript -const ws = new WebSocket('ws://localhost:9471/ws'); - -ws.onopen = () => { - ws.send(JSON.stringify({ - type: 'query', - sql: 'SELECT * FROM users' - })); -}; - -ws.onmessage = (event) => { - console.log('Received:', JSON.parse(event.data)); -}; -``` - -## 消息格式 - -```json -{ - "type": "query", - "id": "uuid", - "sql": "SELECT * FROM users" -} -``` - -## 消息类型 - -### 查询请求 - -```json -{ - "type": "query", - "id": "123", - "sql": "SELECT * FROM users" -} -``` - -### 查询响应 - -```json -{ - "type": "result", - "id": "123", - "data": [{"id": 1, "name": "Alice"}] -} -``` - -### 订阅 - -```json -{ - "type": "subscribe", - "table": "users" -} -``` \ No newline at end of file diff --git a/docs/zh/architecture.md b/docs/zh/architecture.md deleted file mode 100644 index 1ccd8f1..0000000 --- a/docs/zh/architecture.md +++ /dev/null @@ -1,197 +0,0 @@ -# BaraDB 架构 - -## 概述 - -BaraDB 是一个**多模态数据库引擎**，使用 Nim 编写，将文档 (KV)、图、向量、列式和全文搜索存储整合在单一引擎中，使用统一的查询语言 **BaraQL**。 - -## 分层架构 - -``` -┌─────────────────────────────────────────────────────────┐ -│ 1. 客户端层 │ -│ 二进制协议 │ HTTP/REST │ WebSocket │ 嵌入式 │ -├─────────────────────────────────────────────────────────┤ -│ 2. 查询层 (BaraQL) │ -│ 词法分析 → 解析 → AST → IR → 优化器 → 代码生成 │ -├─────────────────────────────────────────────────────────┤ -│ 3. 执行引擎 │ -│ 文档 │ 图 │ 向量 │ 列式 │ FTS │ -├─────────────────────────────────────────────────────────┤ -│ 4. 存储层 │ -│ LSM-Tree │ B-Tree │ WAL │ Bloom │ 压缩 │ 缓存 │ -├─────────────────────────────────────────────────────────┤ -│ 5. 分布式 │ -│ Raft 共识 │ 分片 │ 复制 │ Gossip │ -└─────────────────────────────────────────────────────────┘ -``` - -## 第1层: 客户端层 - -多种通信协议: - -- **二进制协议** (`protocol/wire.nim`): 高效的 big-endian 二进制协议，包含 16 种消息类型 -- **HTTP/REST** (`core/httpserver.nim`): 基于 JSON 的 REST API，支持多线程 -- **WebSocket** (`core/websocket.nim`): 全双工流式传输 -- **嵌入式** (`storage/lsm.nim`): 进程内直接访问 - -### 连接管理 - -- **连接池** (`protocol/pool.nim`): 最小/最大连接限制，空闲超时 -- **限流** (`protocol/ratelimit.nim`): Token-bucket 全局限流和每客户端限流 -- **认证** (`protocol/auth.nim`): HMAC-SHA256 的 JWT 和基于角色的访问 -- **TLS/SSL** (`protocol/ssl.nim`): TLS 1.3，自动生成证书 - -## 第2层: 查询层 (BaraQL) - -BaraQL 处理管道: - -1. **词法分析器** (`query/lexer.nim`): 将输入标记化为 80+ 种标记类型 -2. **解析器** (`query/parser.nim`): 递归下降解析器，生成 AST -3. **AST** (`query/ast.nim`): 300+ 行代码，覆盖 25+ 种节点类型 -4. **IR** (`query/ir.nim`): 用于执行计划的中间表示 -5. **优化器** (`query/adaptive.nim`): 自适应跨模态查询优化 -6. **代码生成** (`query/codegen.nim`): 将 IR 转换为存储操作 -7. **执行器** (`query/executor.nim`): 并行执行计划 - -### 跨模态规划 - -优化器 (`query/adaptive.nim`) 确定跨引擎的执行顺序: - -``` -1. 估算每个谓词的选择性 -2. 将选择性最高的谓词首先推送到其引擎 -3. 使用 Bloom 过滤器进行 KV 查找 -4. 并行化独立分支 -5. 流式传输结果以避免物化 -``` - -## 第3层: 执行引擎 - -### 文档/KV 引擎 -- **LSM-Tree** (`storage/lsm.nim`): 写优化的存储，包含 MemTable、WAL、SSTables -- **B-Tree 索引** (`storage/btree.nim`): 用于范围扫描的有序索引，支持 COW - -### 向量引擎 (`vector/`) -- **HNSW 索引** (`vector/engine.nim`): 分层可导航小世界图 -- **IVF-PQ 索引** (`vector/engine.nim`): 倒排文件索引，带乘积量化 -- **SIMD 操作** (`vector/simd.nim`): AVX2 优化的距离计算 -- **量化** (`vector/quant.nim`): 标量、乘积和二进制量化 - -### 图引擎 (`graph/`) -- **邻接表** (`graph/engine.nim`): 带边权重的有向图 -- **算法** (`graph/engine.nim`): BFS、DFS、Dijkstra、PageRank -- **社区检测** (`graph/community.nim`): Louvain 算法 -- **模式匹配** (`graph/community.nim`): 子图同构 -- **Cypher 解析器** (`graph/cypher.nim`): 类似 Cypher 的图查询 - -### 全文搜索 (`fts/`) -- **倒排索引** (`fts/engine.nim`): 词-文档索引 -- **排名** (`fts/engine.nim`): BM25 和 TF-IDF 评分 -- **模糊搜索** (`fts/engine.nim`): 基于 Levenshtein 距离的匹配 -- **多语言** (`fts/multilang.nim`): EN、BG、DE、FR、RU 的分词器 - -### 列式引擎 (`core/columnar.nim`) -- 用于分析查询的按列存储 -- RLE 和字典编码 -- SIMD 加速的聚合操作 - -## 第4层: 存储 - -- **LSM-Tree** (`storage/lsm.nim`): MemTable、WAL、SSTable、Bloom Filter、压缩 -- **页面缓存** (`storage/compaction.nim`): LRU 缓存，支持命中率追踪 -- **内存映射 I/O** (`storage/mmap.nim`): 基于 mmap 的文件访问 -- **恢复** (`storage/recovery.nim`): WAL 重放和崩溃恢复 - -### 写路径 - -``` -客户端 → 协议 → 认证 → 解析 → AST → IR → 代码生成 - → StorageOp → MVCC Txn → WAL 写入 → MemTable → 提交 -``` - -### 读路径 - -``` -客户端 → 协议 → 认证 → 解析 → AST → IR → 代码生成 - → StorageOp → MVCC 快照 → MemTable → SSTable → 结果 -``` - -## 第5层: 分布式 - -- **Raft 共识** (`core/raft.nim`): 领导者选举、日志复制 -- **分片** (`core/sharding.nim`): 哈希、范围和一致性哈希 -- **复制** (`core/replication.nim`): 同步、异步、半同步模式 -- **Gossip 协议** (`core/gossip.nim`): SWIM 风格的成员管理 -- **分布式事务** (`core/disttxn.nim`): 两阶段提交 - -## 关键设计决策 - -1. **纯 Nim**: 无 Cython、Python 或 Rust 依赖 -2. **统一存储**: 一个引擎处理 KV、图、向量、FTS 和列式存储 -3. **嵌入式模式**: 可作为库或服务器运行 -4. **二进制协议**: 自定义高效有线协议 -5. **MVCC**: 多版本并发控制 -6. **模式优先**: 带继承的强类型模式系统 -7. **跨模态**: 跨所有数据模型的单一查询语言 -8. **形式化验证**: 核心分布式算法使用 TLA+ 规范并用 TLC 模型检查 - -## 模块统计 - -| 类别 | 模块数 | 代码行数 | 用途 | -|------|--------|----------|------| -| Core | 16 | ~4,200 | 服务器、协议、事务、分布式 | -| Storage | 7 | ~3,100 | LSM、B-Tree、WAL、bloom、压缩、mmap | -| Query | 7 | ~2,800 | 词法分析、解析、AST、IR、优化器、代码生成、执行器 | -| Vector | 3 | ~1,200 | HNSW、IVF-PQ、量化、SIMD | -| Graph | 3 | ~1,000 | 邻接表、算法、社区检测 | -| FTS | 2 | ~900 | 倒排索引、BM25、模糊搜索、多语言 | -| Protocol | 7 | ~2,400 | Wire、HTTP、WebSocket、连接池、认证、限流、SSL | -| Schema | 1 | ~600 | 类型、链接、继承、迁移 | -| Client | 2 | ~800 | Nim 二进制客户端、文件助手 | -| CLI | 1 | ~400 | 交互式 BaraQL shell | -| **总计** | **49** | **~14,100** | | - -## 数据流图 - -### 简单查询 - -``` -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ -│ Client │───→│ Lexer │───→│ Parser │───→│ IR │───→│ Codegen│ -└────────┘ └────────┘ └────────┘ └────────┘ └───┬────┘ - │ -┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ -│ Result │←───│ Format │←───│ Execute│←───│ Storage│←──────┘ -└────────┘ └────────┘ └────────┘ └────────┘ -``` - -### 跨模态查询 - -``` - ┌─────────────┐ - │ Parser │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Adaptive │ - │ Optimizer │ - └──────┬──────┘ - │ - ┌───────────────┼───────────────┐ - │ │ │ - ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ - │ Vector │ │ Graph │ │ FTS │ - │ Engine │ │ Engine │ │ Engine │ - └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ - │ │ │ - └───────────────┼───────────────┘ - │ - ┌──────▼──────┐ - │ Join │ - │ & Sort │ - └──────┬──────┘ - │ - ┌──────▼──────┐ - │ Result │ - └─────────────┘ -``` \ No newline at end of file diff --git a/docs/zh/backup.md b/docs/zh/backup.md deleted file mode 100644 index bd439af..0000000 --- a/docs/zh/backup.md +++ /dev/null @@ -1,82 +0,0 @@ -# 备份与恢复 - -## 在线快照 - -BaraDB 支持在线快照，无需停止服务器。快照使用 MVCC 捕获一致的时间点视图。 - -### 创建快照 - -```nim -import barabadb/core/backup - -var bm = newBackupManager() -bm.createSnapshot("/backup/baradb_2025-01-15") -``` - -### 通过 CLI - -```bash -./build/baradadb --snapshot --output=/backup/snapshot.db -``` - -### 通过 HTTP API - -```bash -curl -X POST http://localhost:9470/api/backup \ - -d '{"destination": "/backup/snapshot.db"}' -``` - -### 自动备份 - -```bash -0 2 * * * /usr/local/bin/baradadb --snapshot --output=/backup/baradb_$(date +\%Y\%m\%d).db -find /backup -name "baradb_*.db" -mtime +7 -delete -``` - -## 时间点恢复 (PITR) - -### 从快照 + WAL 恢复 - -```bash -./build/baradadb --recover \ - --checkpoint=/backup/snapshot.db \ - --wal-dir=/backup/wal -``` - -### 通过 SQL 恢复 - -```sql -RECOVER TO TIMESTAMP '2026-05-07T12:00:00'; -``` - -## 灾难恢复场景 - -### 场景 1：文件损坏 - -```bash -cp /backup/sstables/000012.sst ./data/sstables/ -./build/baradadb --rebuild-index -``` - -### 场景 2：完全数据丢失 - -```bash -cp /backup/snapshot.db ./data/ -./build/baradadb --recover --wal-dir=/backup/wal -``` - -### 场景 3：集群节点故障 - -```bash -BARADB_RAFT_NODE_ID=newnode \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## 最佳实践 - -1. 定期测试恢复 -2. 将备份存储在场外 -3. 加密备份 -4. 监控备份作业 -5. 记录 RTO/RPO \ No newline at end of file diff --git a/docs/zh/baraql.md b/docs/zh/baraql.md deleted file mode 100644 index 1f7853d..0000000 --- a/docs/zh/baraql.md +++ /dev/null @@ -1,597 +0,0 @@ -# BaraQL - 查询语言参考 - -BaraQL 是一个与 SQL 兼容的查询语言，包含图、向量和文档操作的扩展。 - -## 数据类型 - -| 类型 | 描述 | 示例 | -|------|------|------| -| `null` | 空值 | `null` | -| `bool` | 布尔值 | `true`, `false` | -| `int8` | 8 位有符号整数 | `127` | -| `int16` | 16 位有符号整数 | `32767` | -| `int32` | 32 位有符号整数 | `2147483647` | -| `int64` | 64 位有符号整数 | `9223372036854775807` | -| `float32` | 32 位浮点数 | `3.14` | -| `float64` | 64 位浮点数 | `3.14159265359` | -| `str` | UTF-8 字符串 | `'hello'` | -| `bytes` | 原始字节 | `0xDEADBEEF` | -| `array` | 同构数组 | `[1, 2, 3]` | -| `vector` | Float32 向量 | `[0.1, 0.2, 0.3]` | -| `object` | 键值对象 | `{"a": 1}` | -| `datetime` | ISO 8601 时间戳 | `'2025-01-15T10:30:00Z'` | -| `uuid` | UUID v4 | `'550e8400-e29b-41d4-a716-446655440000'` | -| `json` | JSON 文档 | `{"key": "value"}` | -| `jsonb` | 二进制 JSON（已验证） | `{"key": "value"}` | - -## 基本查询 - -### SELECT - -```sql --- 所有列 -SELECT * FROM users; - --- 特定列 -SELECT name, age FROM users; - --- 别名 -SELECT name AS full_name, age AS years FROM users; - --- DISTINCT -SELECT DISTINCT department FROM employees; - --- LIMIT 和 OFFSET -SELECT * FROM users LIMIT 10 OFFSET 20; -``` - -### WHERE - -```sql --- 比较运算符 -SELECT * FROM users WHERE age > 18; -SELECT * FROM users WHERE age >= 18 AND age <= 65; -SELECT * FROM users WHERE name = 'Alice'; -SELECT * FROM users WHERE name != 'Bob'; - --- 范围 -SELECT * FROM users WHERE age BETWEEN 18 AND 65; - --- 集合成员 -SELECT * FROM users WHERE department IN ('Engineering', 'Sales'); - --- 模式匹配 -SELECT * FROM users WHERE name LIKE 'A%'; -SELECT * FROM users WHERE name ILIKE 'alice'; -- 不区分大小写 - --- NULL 检查 -SELECT * FROM users WHERE email IS NOT NULL; - --- 逻辑运算符 -SELECT * FROM users WHERE age > 18 AND (department = 'Engineering' OR department = 'Sales'); -``` - -### ORDER BY - -```sql --- 升序（默认） -SELECT * FROM users ORDER BY age; - --- 降序 -SELECT * FROM users ORDER BY age DESC; - --- 多列 -SELECT * FROM users ORDER BY department ASC, age DESC; -``` - -### INSERT - -```sql --- 单行 -INSERT users { name := 'Alice', age := 30 }; - --- 显式类型 -INSERT User { name := 'Alice', age := 30 }; - --- 多行 -INSERT users { - { name := 'Alice', age := 30 }, - { name := 'Bob', age := 25 } -}; -``` - -### UPDATE - -```sql --- 更新所有行 -UPDATE users SET status = 'active'; - --- 条件更新 -UPDATE users SET age = 31 WHERE name = 'Alice'; - --- 更新多列 -UPDATE users SET age = 32, status = 'premium' WHERE name = 'Alice'; -``` - -### DELETE - -```sql --- 删除所有行 -DELETE FROM users; - --- 条件删除 -DELETE FROM users WHERE age < 18; -``` - -## 聚合和分组 - -### 聚合函数 - -| 函数 | 描述 | -|------|------| -| `count(*)` | 计算所有行 | -| `count(column)` | 计算非 NULL 值 | -| `sum(column)` | 值之和 | -| `avg(column)` | 平均值 | -| `min(column)` | 最小值 | -| `max(column)` | 最大值 | -| `stddev(column)` | 标准差 | -| `variance(column)` | 方差 | - -### GROUP BY - -```sql -SELECT department, count(*) as emp_count, avg(salary) as avg_salary -FROM employees -GROUP BY department; - --- 带 HAVING -SELECT department, count(*) as emp_count -FROM employees -GROUP BY department -HAVING count(*) > 5; - --- 多重分组 -SELECT department, role, count(*), avg(salary) -FROM employees -GROUP BY department, role; -``` - -## JOIN - -```sql --- INNER JOIN -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; - --- LEFT JOIN -SELECT u.name, o.total -FROM users u -LEFT JOIN orders o ON u.id = o.user_id; - --- RIGHT JOIN -SELECT u.name, o.total -FROM users u -RIGHT JOIN orders o ON u.id = o.user_id; - --- FULL JOIN -SELECT u.name, o.total -FROM users u -FULL JOIN orders o ON u.id = o.user_id; - --- CROSS JOIN -SELECT u.name, p.name -FROM users u -CROSS JOIN products p; - --- 多重 JOIN -SELECT u.name, o.id, p.name -FROM orders o -JOIN users u ON o.user_id = u.id -JOIN products p ON o.product_id = p.id; - --- Self JOIN -SELECT e.name, m.name as manager -FROM employees e -JOIN employees m ON e.manager_id = m.id; -``` - -## CTE（公用表表达式） - -```sql --- 单个 CTE -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; - --- 多个 CTE -WITH - recent AS ( - SELECT * FROM orders WHERE date > '2025-01-01' - ), - totals AS ( - SELECT user_id, sum(amount) as total FROM recent GROUP BY user_id - ) -SELECT u.name, t.total -FROM users u -JOIN totals t ON u.id = t.user_id; - --- 递归 CTE -WITH RECURSIVE subordinates AS ( - SELECT id, name, manager_id FROM employees WHERE name = 'CEO' - UNION ALL - SELECT e.id, e.name, e.manager_id - FROM employees e - JOIN subordinates s ON e.manager_id = s.id -) -SELECT * FROM subordinates; -``` - -## 子查询 - -```sql --- SELECT 中的子查询 -SELECT name, (SELECT count(*) FROM orders WHERE user_id = u.id) as order_count -FROM users u; - --- FROM 中的子查询 -SELECT * FROM (SELECT id, name FROM users WHERE active = true) AS active; - --- WHERE 中的子查询 (IN) -SELECT name FROM users WHERE id IN (SELECT user_id FROM orders); - --- WHERE 中的子查询 (EXISTS) -SELECT name FROM users WHERE EXISTS (SELECT 1 FROM orders WHERE orders.user_id = users.id); - --- 相关子查询 -SELECT name FROM users u -WHERE age > (SELECT avg(age) FROM users WHERE department = u.department); -``` - -## CASE 表达式 - -```sql -SELECT name, - CASE - WHEN age < 13 THEN 'child' - WHEN age < 20 THEN 'teenager' - WHEN age < 65 THEN 'adult' - ELSE 'senior' - END AS category -FROM users; - --- 简单 CASE -SELECT name, - CASE department - WHEN 'Engineering' THEN 'Tech' - WHEN 'Sales' THEN 'Revenue' - ELSE 'Other' - END AS division -FROM employees; -``` - -## 集合运算 - -```sql --- UNION（去重） -SELECT name FROM customers -UNION -SELECT name FROM suppliers; - --- UNION ALL（保留重复） -SELECT name FROM customers -UNION ALL -SELECT name FROM suppliers; - --- INTERSECT -SELECT name FROM customers -INTERSECT -SELECT name FROM suppliers; - --- EXCEPT -SELECT name FROM customers -EXCEPT -SELECT name FROM suppliers; -``` - -## 模式定义 - -### CREATE TYPE - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - --- 带必填字段 -CREATE TYPE User { - email: str REQUIRED, - name: str, - age: int32, - created_at: datetime DEFAULT now() -}; - --- 带链接 -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; - --- 带计算属性 -CREATE TYPE Employee { - name: str, - base_salary: float64, - bonus: float64, - total_compensation: float64 COMPUTED (base_salary + bonus) -}; -``` - -### 继承 - -```sql -CREATE TYPE Animal { - name: str -}; - -CREATE TYPE Dog EXTENDING Animal { - breed: str -}; - -CREATE TYPE Cat EXTENDING Animal { - indoor: bool -}; -``` - -### 索引 - -```sql -CREATE INDEX idx_users_name ON users(name); -CREATE UNIQUE INDEX idx_users_email ON users(email); -CREATE INDEX idx_users_age ON users(age) USING btree; -``` - -### DROP - -```sql -DROP TYPE User; -DROP INDEX idx_users_name; -``` - -## 向量搜索 - -```sql --- 插入向量 -INSERT articles { - title := 'Nim Programming', - embedding := [0.1, 0.2, 0.3, 0.4] -}; - --- 相似性搜索（余弦距离） -SELECT title FROM articles -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- 欧几里得距离 -SELECT title FROM articles -ORDER BY l2_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; - --- 点积 -SELECT title FROM articles -ORDER BY dot_product(embedding, [0.1, 0.2, 0.3, 0.4]) DESC -LIMIT 5; - --- 带元数据过滤 -SELECT title FROM articles -WHERE category = 'tech' -ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3, 0.4]) -LIMIT 5; -``` - -## 图模式 - -```sql --- 查找 Alice 的朋友 -MATCH (p:Person)-[:KNOWS]->(friend:Person) -WHERE p.name = 'Alice' -RETURN friend.name; - --- 查找最短路径 -MATCH path = shortestPath((a:Person)-[:KNOWS*1..5]->(b:Person)) -WHERE a.name = 'Alice' AND b.name = 'Bob' -RETURN path; - --- 查找所有关系 -MATCH (p:Person)-[r]->(other) -WHERE p.name = 'Alice' -RETURN type(r), other.name; - --- 多跳 -MATCH (a:Person)-[:KNOWS]->(b:Person)-[:KNOWS]->(c:Person) -WHERE a.name = 'Alice' -RETURN c.name; - --- 带聚合 -MATCH (p:Person)-[:KNOWS]->(friend) -RETURN p.name, count(friend) as friend_count -ORDER BY friend_count DESC; -``` - -## 全文搜索 - -```sql --- 基本搜索 -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('database programming'); - --- 带相关性评分 -SELECT title, relevance() -FROM articles -WHERE MATCH(title, body) AGAINST('Nim language') -ORDER BY relevance() DESC; - --- 布尔模式 -SELECT * FROM articles -WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE); - --- 模糊搜索 -SELECT * FROM articles -WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2); -``` - -## 事务 - -```sql -BEGIN; -INSERT users { name := 'Alice', age := 30 }; -INSERT orders { user_id := last_insert_id(), total := 100 }; -COMMIT; - --- 带保存点 -BEGIN; -INSERT users { name := 'Bob', age := 25 }; -SAVEPOINT sp1; -INSERT orders { user_id := last_insert_id(), total := 200 }; --- 哎呀，回滚到保存点 -ROLLBACK TO sp1; -COMMIT; -``` - -## 用户定义函数 - -```sql --- 注册 UDF -CREATE FUNCTION greet(name str) -> str { - RETURN 'Hello, ' || name || '!'; -}; - --- 使用 -SELECT greet(name) FROM users; - --- 内置函数 -SELECT abs(-5), sqrt(16), lower('HELLO'), len('test'); -``` - -## 查询提示 - -```sql --- 强制使用索引 -SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18; - --- 强制近似向量搜索 -SELECT /*+ APPROXIMATE */ * FROM vectors -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; - --- 并行执行 -SELECT /*+ PARALLEL(4) */ * FROM large_table; -``` - -## 窗口函数 - -```sql --- 排名函数 -SELECT - name, - department, - ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn, - RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r, - DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr -FROM employees; - --- 值函数 -SELECT - name, - salary, - LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary, - LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary, - FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest, - LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive -FROM employees; - --- 分布函数 -SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees; -``` - -### 帧规格 - -```sql --- ROWS 帧 -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - ROWS BETWEEN 1 PRECEDING AND CURRENT ROW -) - --- RANGE 帧 -SUM(salary) OVER ( - PARTITION BY department - ORDER BY hire_date - RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW -) -``` - -## 多租户 ERP - -BaraDB 支持在单个数据库实例中运行多个公司（租户），使用**行级安全性（RLS）**结合**会话变量**。 - -### 会话变量 - -```sql -SET app.tenant_id = 'company-123'; -SELECT current_setting('app.tenant_id') AS tenant; -``` - -### 当前用户 / 角色 - -```sql -SELECT current_user AS me, current_role AS my_role; -``` - -### RLS 租户隔离 - -```sql --- 在表上启用 RLS -ALTER TABLE invoices ENABLE ROW LEVEL SECURITY; - --- 创建按租户过滤的策略 -CREATE POLICY tenant_isolation ON invoices - FOR SELECT USING (tenant_id = current_setting('app.tenant_id')); - --- 每个会话只能看到自己的数据 -SET app.tenant_id = 'company-a'; -SELECT * FROM invoices; -- 仅限 company-a 的行 -``` - -### 为什么选择多租户？ - -- **一个实例，多个租户** — 无需运行 100 个独立的数据库 -- **JSONB 文档** — 模式灵活的存储，易于为每个租户添加字段 -- **RLS 保证隔离** — 数据库强制执行租户边界，而不仅仅是应用程序 - -## 支持的关键字 - -| 类别 | 关键字 | -|----------|----------| -| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT | -| DML | INSERT, UPDATE, DELETE, SET, VALUES | -| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE | -| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON | -| Set | UNION, UNION ALL, INTERSECT, EXCEPT | -| CTEs | WITH, RECURSIVE, AS | -| Case | CASE, WHEN, THEN, ELSE, END | -| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT | -| Graph | MATCH, RETURN, WHERE, shortestPath, type | -| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS | -| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> | -| JSON | ->, ->> | -| FTS | @@ (BM25 match) | -| Recovery | RECOVER TO TIMESTAMP | -| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting | -| Session | SET, current_setting, current_user, current_role | -| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING | -| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE | \ No newline at end of file diff --git a/docs/zh/btree.md b/docs/zh/btree.md deleted file mode 100644 index 02a73ae..0000000 --- a/docs/zh/btree.md +++ /dev/null @@ -1,26 +0,0 @@ -# B-Tree 索引 - -用于高效范围扫描和点查询的有序索引结构。 - -## 用法 - -```nim -import barabadb/storage/btree - -var btree = newBTreeIndex[string, string]() - -btree.insert("key1", "value1") -btree.insert("key2", "value2") - -let values = btree.get("key1") -let range = btree.scan("key_a", "key_z") -btree.delete("key1") -``` - -## 特性 - -- 有序键值存储 -- 范围查询（BETWEEN, >, <, >=, <=） -- 前缀扫描 -- 可配置的页面大小 -- 迭代器支持 \ No newline at end of file diff --git a/docs/zh/changelog.md b/docs/zh/changelog.md deleted file mode 100644 index 6bc07c6..0000000 --- a/docs/zh/changelog.md +++ /dev/null @@ -1,76 +0,0 @@ -# 更新日志 - -## [0.1.0] — 2025-01-15 - -### 新增功能 - -- **核心存储引擎** - - LSM-Tree 包含 MemTable、WAL、SSTables 和 size-tiered compaction - - B-Tree 有序索引支持范围扫描和 MVCC copy-on-write - - Bloom 过滤器优化 SSTable 跳过 - - Memory-mapped I/O - - LRU 页面缓存 - -- **查询引擎 (BaraQL)** - - SQL 兼容的词法分析器，80+ 种标记类型 - - 递归下降解析器，生成 25+ 种节点类型的 AST - - 中间表示（IR） - - 自适应查询优化器，支持跨模态规划 - - 并行查询执行器 - -- **BaraQL 语言功能** - - SELECT、INSERT、UPDATE、DELETE - - WHERE、ORDER BY、LIMIT、OFFSET - - GROUP BY、HAVING、聚合函数 - - INNER JOIN、LEFT JOIN、RIGHT JOIN、FULL JOIN、CROSS JOIN - - CTEs (WITH) - - 子查询 - - CASE 表达式 - - UNION、INTERSECT、EXCEPT - -- **向量引擎** - - HNSW 近似最近邻搜索 - - IVF-PQ 大规模向量搜索 - - SIMD 优化的距离函数 - - 量化：标量 8-bit/4-bit、乘积量化、二进制 - -- **图引擎** - - 邻接表存储 - - BFS 和 DFS 遍历 - - Dijkstra 最短路径 - - PageRank - - Louvain 社区检测 - - Cypher 查询解析器 - -- **全文搜索** - - 倒排索引 - - BM25 排名 - - TF-IDF - - 模糊搜索 - - 多语言分词器 - -- **协议** - - Binary wire protocol - - HTTP/REST JSON API - - WebSocket - - Connection pooling - - JWT 认证 - - TLS/SSL - -- **分布式系统** - - Raft 共识 - - Hash、range、consistent-hash 分片 - - 同步/异步/半同步复制 - - Gossip 协议 - - 两阶段提交 - -### 性能 - -- LSM-Tree: 580K 写入/秒，720K 读取/秒 -- B-Tree: 1.2M 插入/秒，1.5M 查找/秒 -- Vector SIMD: 850K 余弦距离/秒（dim=768） - -### 测试 - -- 56 个测试套件中的 262 个测试 -- 100% 通过率 \ No newline at end of file diff --git a/docs/zh/clients.md b/docs/zh/clients.md deleted file mode 100644 index e0dc36a..0000000 --- a/docs/zh/clients.md +++ /dev/null @@ -1,66 +0,0 @@ -# 客户端 SDK - -BaraDB 为 JavaScript/TypeScript、Python、Nim 和 Rust 提供官方客户端库。 - -## JavaScript / TypeScript - -### 安装 - -```bash -npm install baradb -``` - -### 基本用法 - -```typescript -import { Client } from 'baradb'; - -const client = new Client('localhost', 9472); -await client.connect(); - -const result = await client.query('SELECT name, age FROM users WHERE age > 18'); -``` - -## Python - -### 安装 - -```bash -pip install baradb -``` - -### 基本用法 - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -result = client.query("SELECT name, age FROM users WHERE age > 18") -``` - -## Nim（嵌入式模式） - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## Rust - -```rust -use baradb::Client; - -let mut client = Client::connect("localhost:9472").await?; -``` - -## HTTP/REST - -```bash -curl -X POST http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` \ No newline at end of file diff --git a/docs/zh/columnar.md b/docs/zh/columnar.md deleted file mode 100644 index e66ec0e..0000000 --- a/docs/zh/columnar.md +++ /dev/null @@ -1,50 +0,0 @@ -# 列式存储 - -用于分析查询和聚合的面向列的存储。 - -## 用法 - -```nim -import barabadb/core/columnar - -var batch = newColumnBatch() -var ageCol = batch.addInt64Col("age") -var nameCol = batch.addStringCol("name") - -ageCol.appendInt64(25) -nameCol.appendString("Alice") -``` - -## 聚合 - -```nim -echo ageCol.sumInt64() -echo ageCol.avgInt64() -echo ageCol.minInt64() -echo ageCol.maxInt64() -``` - -## 编码 - -### RLE - -```nim -let rle = rleEncode(@[1'i64, 1, 1, 2, 2, 3]) -``` - -### Dictionary - -```nim -let dict = dictEncode(@["apple", "banana", "apple"]) -``` - -## 列类型 - -| 类型 | 描述 | -|------|------| -| `int32` | 32 位整数 | -| `int64` | 64 位整数 | -| `float32` | 32 位浮点数 | -| `float64` | 64 位浮点数 | -| `string` | 可变长度字符串 | -| `bool` | 布尔值 | \ No newline at end of file diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md deleted file mode 100644 index f90db00..0000000 --- a/docs/zh/configuration.md +++ /dev/null @@ -1,217 +0,0 @@ -# BaraDB - 配置参考 - -BaraDB 可以通过**环境变量**、**配置文件**或**命令行标志**进行配置。 - -## 优先级顺序 - -1. 命令行标志（最高优先级） -2. 环境变量 -3. 配置文件 (`baradb.conf` 或 `baradb.json`) -4. 内置默认值（最低优先级） - -## 环境变量 - -### 网络 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_ADDRESS` | `127.0.0.1` | 绑定地址 | -| `BARADB_PORT` | `9472` | TCP 二进制协议端口 | -| `BARADB_HTTP_PORT` | `9470` | HTTP/REST API 端口 | -| `BARADB_WS_PORT` | `9471` | WebSocket 端口 | - -### 存储 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_DATA_DIR` | `./data` | 数据目录路径 | -| `BARADB_MEMTABLE_SIZE_MB` | `64` | MemTable 大小（MB） | -| `BARADB_CACHE_SIZE_MB` | `256` | 页面缓存大小（MB） | -| `BARADB_WAL_SYNC_INTERVAL_MS` | `0` | WAL fsync 间隔（0 = 每次写入） | -| `BARADB_COMPACTION_INTERVAL_MS` | `60000` | 后台压缩间隔 | -| `BARADB_BLOOM_BITS_PER_KEY` | `10` | 每个键的 Bloom 过滤器位数 | - -### TLS/SSL - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_TLS_ENABLED` | `false` | 启用 TLS | -| `BARADB_CERT_FILE` | — | TLS 证书路径 | -| `BARADB_KEY_FILE` | — | TLS 私钥路径 | - -### 安全 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_AUTH_ENABLED` | `false` | 启用认证 | -| `BARADB_JWT_SECRET` | — | JWT 签名密钥 | -| `BARADB_RATE_LIMIT_GLOBAL` | `10000` | 全局请求数/秒 | -| `BARADB_RATE_LIMIT_PER_CLIENT` | `1000` | 每客户端请求数/秒 | - -### 日志 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_LOG_LEVEL` | `info` | 日志级别：debug, info, warn, error | -| `BARADB_LOG_FILE` | — | 日志文件路径（空则输出到 stdout） | -| `BARADB_LOG_FORMAT` | `json` | 日志格式：json, text | - -### 向量引擎 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_VECTOR_M` | `16` | HNSW `M` 参数 | -| `BARADB_VECTOR_EF_CONSTRUCTION` | `200` | HNSW `efConstruction` | -| `BARADB_VECTOR_EF_SEARCH` | `64` | HNSW `efSearch` | - -### 图引擎 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_GRAPH_PAGE_RANK_ITERATIONS` | `20` | PageRank 迭代次数 | -| `BARADB_GRAPH_PAGE_RANK_DAMPING` | `0.85` | PageRank 阻尼因子 | -| `BARADB_GRAPH_LOUVAIN_RESOLUTION` | `1.0` | Louvain 分辨率参数 | - -### 分布式 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_RAFT_NODE_ID` | — | 集群中的唯一节点 ID | -| `BARADB_RAFT_PEERS` | — | 逗号分隔的节点地址列表 | -| `BARADB_RAFT_PORT` | `9001` | Raft 内部通信端口 | -| `BARADB_SHARD_COUNT` | `1` | 分片数量 | -| `BARADB_REPLICATION_FACTOR` | `1` | 复制因子 | - -## 配置文件 - -### baradb.conf (INI 风格) - -```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" - } -} -``` - -## 命令行标志 - -```bash -./build/baradadb --help -``` - -``` -BaraDB v1.1.6 — Multimodal Database Engine - -Usage: - baradadb [options] - -Options: - -c, --config 配置文件路径 - -p, --port TCP 二进制端口（默认：9472） - --http-port HTTP 端口（默认：9470） - --ws-port WebSocket 端口（默认：9471） - -d, --data-dir 数据目录（默认：./data） - --tls-cert TLS 证书文件 - --tls-key TLS 私钥文件 - --log-level 日志级别：debug, info, warn, error - --log-file 日志文件路径 - --shell 启动交互式 shell - --version 显示版本 - --recover 运行 WAL 恢复 - --checkpoint 用于恢复的检查点 - -h, --help 显示此帮助信息 -``` - -## 配置示例 - -### 开发环境 - -```bash -./build/baradadb \ - --log-level debug \ - --data-dir ./dev_data -``` - -### 生产环境单节点 - -```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 -``` - -### 生产环境集群（3 节点） - -```bash -# 节点 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 -``` \ No newline at end of file diff --git a/docs/zh/crossmodal.md b/docs/zh/crossmodal.md deleted file mode 100644 index 0344167..0000000 --- a/docs/zh/crossmodal.md +++ /dev/null @@ -1,48 +0,0 @@ -# 跨模态查询 - -BaraDB 的独特能力是执行跨越多个存储引擎的查询，使用单一的 BaraQL 语句。 - -## 概述 - -- **文档/KV** (LSM-Tree) — 结构化记录 -- **图** (邻接表) — 关系 -- **向量** (HNSW/IVF-PQ) — 相似性搜索 -- **全文** (倒排索引) — 文本搜索 -- **列式** — 分析聚合 - -## 查询模式 - -### 向量 + 全文 - -```sql -SELECT title FROM articles -WHERE MATCH(body) AGAINST('machine learning') -ORDER BY cosine_distance(embedding, [...]) -LIMIT 10; -``` - -### 图 + 向量 - -```sql -MATCH (u:User)-[:KNOWS]->(friend:User) -WHERE u.name = 'Alice' -ORDER BY cosine_distance(friend.taste_vector, u.taste_vector) -RETURN friend.name; -``` - -## 优化 - -### 跨模态查询规划器 - -1. 最具选择性的过滤器优先 -2. 将谓词下推到每个引擎 -3. 使用 Bloom 过滤器进行 KV 查找 -4. 并行化独立分支 - -## 性能 - -| 查询类型 | 延迟（10K 行） | -|----------|-----------------| -| FTS + Vector | 15 ms | -| Graph + Vector | 25 ms | -| FTS + Aggregate | 12 ms | \ No newline at end of file diff --git a/docs/zh/deployment.md b/docs/zh/deployment.md deleted file mode 100644 index be642fd..0000000 --- a/docs/zh/deployment.md +++ /dev/null @@ -1,249 +0,0 @@ -# BaraDB - 部署指南 - -## Docker - -完整的 Docker 部署指南请参见 [Docker 指南](docker.md)。 - -### 快速开始 - -```bash -docker build -t baradb:latest . -docker compose up -d -``` - -### Docker Compose 文件 - -| 文件 | 用途 | -|------|------| -| `docker-compose.yml` | 开发环境 | -| `docker-compose.prod.yml` | 生产环境 | -| `docker-compose.override.yml` | 开发覆盖（自动） | - -### 生产环境 - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -### Docker Swarm - -```bash -docker stack deploy -c docker-compose.prod.yml baradb -``` - -## systemd 服务 - -创建 `/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 - -# 安全加固 -NoNewPrivileges=true -ProtectSystem=strict -ProtectHome=true -ReadWritePaths=/var/lib/baradb/data -ProtectKernelTunables=true -ProtectKernelModules=true -ProtectControlGroups=true - -[Install] -WantedBy=multi-user.target -``` - -启用并启动: - -```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 -``` - -## 反向代理 (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"; - } -} -``` - -## 高可用性 - -### 3 节点 Raft 集群 - -```bash -# 节点 1 -BARADB_RAFT_NODE_ID=node1 \ -BARADB_RAFT_PEERS=node2:9001,node3:9001 \ -./build/baradadb - -# 节点 2 -BARADB_RAFT_NODE_ID=node2 \ -BARADB_RAFT_PEERS=node1:9001,node3:9001 \ -./build/baradadb - -# 节点 3 -BARADB_RAFT_NODE_ID=node3 \ -BARADB_RAFT_PEERS=node1:9001,node2:9001 \ -./build/baradadb -``` - -## 云部署 - -### AWS EC2 - -推荐实例: `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（仅 HTTP） - -```bash -gcloud run deploy baradb \ - --image gcr.io/PROJECT/baradb \ - --port 9470 \ - --memory 4Gi \ - --cpu 2 \ - --max-instances 10 -``` \ No newline at end of file diff --git a/docs/zh/distributed.md b/docs/zh/distributed.md deleted file mode 100644 index 7d6a84e..0000000 --- a/docs/zh/distributed.md +++ /dev/null @@ -1,91 +0,0 @@ -# 分布式系统 - -BaraDB 支持使用 Raft 共识、分片和复制进行分布式部署。 - -## Raft 共识 - -领导者选举和日志复制： - -```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() -``` - -## 分片 - -跨节点分发数据： - -```nim -import barabadb/core/sharding - -var router = newShardRouter(ShardConfig( - numShards: 4, - replicas: 2, - strategy: ssHash -)) -router.rebalance(@["node1", "node2", "node3"]) -``` - -### 分片策略 - -| 策略 | 描述 | -|------|------| -| `ssHash` | 基于哈希的分片 | -| `ssRange` | 基于范围的分片 | -| `ssConsistent` | 一致性哈希 | - -## 复制 - -```nim -import barabadb/core/replication - -var rm = newReplicationManager(rmSync) -rm.addReplica(newReplica("r1", "10.0.0.1", 9472)) -``` - -### 复制模式 - -| 模式 | 描述 | -|------|------| -| `rmSync` | 同步复制 | -| `rmAsync` | 异步复制 | -| `rmSemiSync` | 半同步复制 | - -## Gossip 协议 - -```nim -import barabadb/core/gossip - -var g = newGossipManager() -g.addNode("node1") -g.addNode("node2") -g.tick() -``` - -## 分布式事务 - -两阶段提交： - -```nim -import barabadb/core/disttxn - -var dt = newDistributedTxn() -dt.prepare(@["node1", "node2"]) -dt.commit() -``` - -## 形式化验证 - -核心分布式算法在 TLA+ 中形式化规范并通过模型检查： - -- **Raft Consensus** — `formal-verification/raft.tla` -- **Two-Phase Commit** — `formal-verification/twopc.tla` -- **Replication** — `formal-verification/replication.tla` \ No newline at end of file diff --git a/docs/zh/docker.md b/docs/zh/docker.md deleted file mode 100644 index 40aab0f..0000000 --- a/docs/zh/docker.md +++ /dev/null @@ -1,129 +0,0 @@ -# Docker 部署指南 - -## 快速开始 - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB - -docker build -t baradb:latest . - -docker compose up -d - -docker compose ps -docker compose logs -f -``` - -## 文件 - -| 文件 | 描述 | -|------|------| -| `Dockerfile` | 多阶段生产构建 | -| `docker-compose.yml` | 开发配置 | -| `docker-compose.prod.yml` | 生产配置 | -| `docker-compose.override.yml` | 开发覆盖（自动加载）| -| `docker-entrypoint.sh` | 初始化入口脚本 | -| `.dockerignore` | 不复制到镜像的文件 | -| `scripts/docker-build.sh` | 构建辅助脚本 | -| `scripts/docker-run.sh` | 运行辅助脚本 | - -## 构建镜像 - -```bash -docker build -t baradb:latest . -./scripts/docker-build.sh -``` - -## 运行 - -### 开发 (docker compose) - -```bash -docker compose up -d -docker compose down -docker compose logs -f -``` - -### 生产 (docker compose) - -```bash -docker compose -f docker-compose.prod.yml up -d -``` - -### 手动 (docker run) - -```bash -docker run -d \ - --name baradb \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - baradb:latest -``` - -## 端口 - -| 端口 | 描述 | -|------|------| -| `9472` | 二进制协议 | -| `9470` | HTTP/REST API | -| `9471` | WebSocket | - -## 环境变量 - -| 变量 | 默认值 | 描述 | -|------|--------|------| -| `BARADB_ADDRESS` | `0.0.0.0` | 监听地址 | -| `BARADB_PORT` | `9472` | 二进制协议端口 | -| `BARADB_HTTP_PORT` | `9470` | HTTP 端口 | -| `BARADB_DATA_DIR` | `/data` | 数据目录 | - -## 卷 - -| 路径 | 描述 | -|------|------| -| `/data` | 主数据目录 | -| `/data/server/wal` | 预写日志 | -| `/data/server/sstables` | SSTable 文件 | - -## 生产检查清单 - -- [ ] 在 `./certs/` 创建 TLS 证书 -- [ ] 设置强 `BARADB_JWT_SECRET` -- [ ] 配置防火墙规则 -- [ ] 配置定期备份 -- [ ] 检查资源限制 -- [ ] 设置监控 - -## Docker 中的 TLS - -```bash -mkdir -p certs -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout certs/server.key -out certs/server.crt -``` - -## Docker 备份 - -```bash -docker exec baradb /app/backup backup --data-dir=/data -docker exec baradb /app/backup list -docker exec baradb /app/backup restore --input=backup_xxx.tar.gz -``` - -## 故障排除 - -### 容器不启动 - -```bash -docker compose logs -f baradb -docker compose ps -``` - -### 无法连接数据库 - -```bash -docker port baradb -docker exec baradb wget -qO- http://localhost:9470/health -``` \ No newline at end of file diff --git a/docs/zh/fts.md b/docs/zh/fts.md deleted file mode 100644 index c5f9a72..0000000 --- a/docs/zh/fts.md +++ /dev/null @@ -1,47 +0,0 @@ -# 全文搜索引擎 - -具有 BM25 和 TF-IDF 排名的倒排索引。 - -## 用法 - -```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") - -let results = idx.search("programming language") -let fuzzy = idx.fuzzySearch("programing", maxDistance = 2) -``` - -## 排名方法 - -### BM25 - -```nim -let bm25 = idx.searchBM25("query terms") -``` - -### TF-IDF - -```nim -let tfidf = idx.searchTfidf("query terms") -``` - -## 搜索功能 - -| 功能 | 描述 | -|------|------| -| Fuzzy search | 允许拼写错误（Levenshtein 距离） | -| Wildcard | 前缀、后缀和中间通配符 | -| Regex | 正则表达式模式 | -| Phrase search | 精确短语匹配 | -| Boolean | AND、OR、NOT 运算符 | - -## SQL 接口 - -```sql -CREATE INDEX idx_fts ON articles(body) USING FTS; -SELECT * FROM articles WHERE body @@ 'machine learning'; -``` \ No newline at end of file diff --git a/docs/zh/graph.md b/docs/zh/graph.md deleted file mode 100644 index 7ba0b47..0000000 --- a/docs/zh/graph.md +++ /dev/null @@ -1,42 +0,0 @@ -# 图引擎 - -具有内置算法的邻接表存储，用于图遍历和分析。 - -## 用法 - -```nim -import barabadb/graph/engine - -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 bfs = g.bfs(alice) -let path = g.shortestPath(alice, bob) -let ranks = g.pageRank() -``` - -## 算法 - -| 算法 | 描述 | -|------|------| -| `bfs` | 广度优先遍历 | -| `dfs` | 深度优先遍历 | -| `dijkstra` | 最短加权路径 | -| `pageRank` | 节点重要性排名 | -| `louvain` | 社区检测 | -| `patternMatch` | 子图同构 | - -## Cypher 查询 - -```nim -import barabadb/graph/cypher - -var engine = newCypherEngine(g) -let results = engine.execute(""" - MATCH (p:Person)-[:KNOWS]->(friend:Person) - WHERE p.name = 'Alice' - RETURN friend.name -""") -``` \ No newline at end of file diff --git a/docs/zh/index.md b/docs/zh/index.md deleted file mode 100644 index d73b485..0000000 --- a/docs/zh/index.md +++ /dev/null @@ -1,59 +0,0 @@ -# BaraDB 文档 (简体中文) - -**使用 Nim 编写的多模态数据库引擎 — 100% 原生实现，零依赖。** - -## 快速链接 - -> **注意：** 中文文档正在开发中。请参阅 [英文版](../en/) 获取完整信息。 - -### 入门指南 -- [安装](../en/installation.md) -- [快速开始](../en/quickstart.md) -- [架构概述](../en/architecture.md) -- [配置参考](../en/configuration.md) -- [部署指南](../en/deployment.md) - -### 核心概念 -- [BaraQL 查询语言](../en/baraql.md) -- [存储引擎](../en/storage.md) -- [模式系统](../en/schema.md) -- [跨模态查询](../en/crossmodal.md) - -### 引擎 -- [LSM-Tree 存储](../en/lsm.md) -- [B-Tree 索引](../en/btree.md) -- [向量搜索](../en/vector.md) -- [图引擎](../en/graph.md) -- [全文搜索](../en/fts.md) -- [列式存储](../en/columnar.md) - -### API 与客户端 -- [客户端 SDK](../en/clients.md) -- [二进制协议](../en/api-binary.md) -- [HTTP/REST API](../en/api-http.md) -- [WebSocket API](../en/api-websocket.md) -- [协议参考](../en/protocol.md) - -### 运维 -- [性能与基准测试](../en/performance.md) -- [安全指南](../en/security.md) -- [监控与可观测性](../en/monitoring.md) -- [备份与恢复](../en/backup.md) -- [故障排除](../en/troubleshooting.md) - -### 高级主题 -- [事务与 MVCC](../en/transactions.md) -- [分布式系统](../en/distributed.md) -- [用户定义函数](../en/udf.md) - ---- - -## 项目信息 - -- [更新日志](../en/changelog.md) -- [许可证](../../LICENSE) -- [GitHub 仓库](https://github.com/katehonz/barabaDB) - ---- - -*中文文档正在翻译中。* \ No newline at end of file diff --git a/docs/zh/installation.md b/docs/zh/installation.md deleted file mode 100644 index 2ae02eb..0000000 --- a/docs/zh/installation.md +++ /dev/null @@ -1,309 +0,0 @@ -# BaraDB - 安装指南 - -## 系统要求 - -- **Nim 编译器** >= 2.2.0 -- **OpenSSL 开发头文件** (用于 TLS 支持) -- **操作系统**: Linux、macOS、Windows - -### 支持的平台 - -| 操作系统 | 架构 | 状态 | -|----------|------|------| -| Linux | x86_64 | ✅ 完全支持 | -| Linux | ARM64 | ✅ 完全支持 | -| macOS | x86_64 | ✅ 完全支持 | -| macOS | ARM64 (Apple Silicon) | ✅ 完全支持 | -| Windows | x86_64 | ✅ 支持 | -| FreeBSD | x86_64 | 🟡 社区测试 | - -## 安装 Nim - -### Linux - -```bash -# 官方安装脚本 -curl https://nim-lang.org/choosenim/init.sh -sSf | sh - -# Ubuntu/Debian -sudo apt-get update -sudo apt-get install nim - -# Fedora -sudo dnf install nim - -# Arch Linux -sudo pacman -S nim -``` - -### macOS - -```bash -# Homebrew -brew install nim - -# MacPorts -sudo port install nim -``` - -### Windows - -```powershell -# 使用 choosenim -curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell - - -# 使用 winget -winget install nim - -# 使用 scoop -scoop install nim -``` - -### 验证安装 - -```bash -nim --version -# 预期输出: Nim Compiler Version 2.2.0 或更高 -``` - -## 安装 OpenSSL - -### Linux - -```bash -# Ubuntu/Debian -sudo apt-get install libssl-dev - -# Fedora -sudo dnf install openssl-devel - -# Arch Linux -sudo pacman -S openssl -``` - -### macOS - -OpenSSL 已随系统提供。如有需要: - -```bash -brew install openssl -``` - -### Windows - -OpenSSL 已捆绑在 Nim Windows 分发版中。如需手动构建， -请从 [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html) 下载。 - -## 构建 BaraDB - -### 克隆仓库 - -```bash -git clone https://codeberg.org/baraba/baradb -cd barabaDB -``` - -### 安装依赖 - -```bash -nimble install -d -y -``` - -### 构建选项 - -#### 调试构建 - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -#### 发布构建 (推荐) - -```bash -nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim -``` - -#### 使用 Nimble Tasks - -```bash -# 调试构建 -nimble build_debug - -# 发布构建 -nimble build_release -``` - -#### 精简二进制文件 - -```bash -nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim -strip build/baradadb -``` - -### 验证构建 - -```bash -./build/baradadb --version -# 预期输出: BaraDB v1.1.6 — Multimodal Database Engine -``` - -## 运行测试 - -### 所有测试 - -```bash -nim c -d:ssl -r tests/test_all.nim -``` - -### 特定测试套件 - -```bash -# 存储测试 -nim c -d:ssl -r tests/test_storage.nim - -# 查询引擎测试 -nim c -d:ssl -r tests/test_query.nim - -# 协议测试 -nim c -d:ssl -r tests/test_protocol.nim -``` - -### 基准测试 - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## 安装选项 - -### 系统级安装 - -```bash -# 构建发布版二进制文件 -nimble build_release - -# 安装到 /usr/local/bin -sudo cp build/baradadb /usr/local/bin/ -sudo chmod +x /usr/local/bin/baradadb - -# 创建数据目录 -sudo mkdir -p /var/lib/baradb -sudo chmod 755 /var/lib/baradb -``` - -### 预编译二进制文件 - -为您的平台下载最新的发布版本: - -```bash -# Linux x86_64 -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 - -# Linux ARM64 -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64 -chmod +x baradadb-linux-arm64 -mv baradadb-linux-arm64 /usr/local/bin/baradadb - -# macOS -wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64 -chmod +x baradadb-darwin-amd64 -mv baradadb-darwin-amd64 /usr/local/bin/baradadb -``` - -### Docker - -```bash -# 拉取官方镜像 -docker pull barabadb/barabadb:latest - -# 运行 -docker run -d \ - -p 9472:9472 \ - -p 9470:9470 \ - -p 9471:9471 \ - -v baradb_data:/data \ - barabadb/barabadb -``` - -### Docker Compose - -```bash -docker-compose up -d -``` - -### 嵌入式使用 (Nim 项目) - -添加到您的 `.nimble` 文件: - -```nim -requires "barabadb >= 0.1.0" -``` - -在代码中使用: - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key", cast[seq[byte]]("value")) -let (found, val) = db.get("key") -db.close() -``` - -## 首次运行 - -```bash -# 启动服务器 -./build/baradadb - -# 预期输出: -# BaraDB v1.1.6 — Multimodal Database Engine -# BaraDB TCP listening on 127.0.0.1:9472 - -# 使用 HTTP API 测试 -curl http://localhost:9470/health - -# 交互式 shell -./build/baradadb --shell -``` - -## 安装故障排除 - -### "cannot open file: hunos" - -```bash -nimble install -d -y -``` - -### "BaraDB requires SSL support" - -始终使用 `-d:ssl` 编译: - -```bash -nim c -d:ssl -o:build/baradadb src/baradadb.nim -``` - -### 编译缓慢 - -使用并行编译: - -```bash -nim c -d:ssl -d:release --parallelBuild:4 -o:build/baradadb src/baradadb.nim -``` - -### 二进制文件过大 - -使用大小优化: - -```bash -nim c -d:ssl -d:release --opt:size --passL:-s -o:build/baradadb src/baradadb.nim -``` - -## 下一步 - -- [快速入门指南](quickstart.md) -- [配置参考](configuration.md) -- [架构概述](architecture.md) -- [BaraQL 查询语言](baraql.md) \ No newline at end of file diff --git a/docs/zh/lsm.md b/docs/zh/lsm.md deleted file mode 100644 index febd7a4..0000000 --- a/docs/zh/lsm.md +++ /dev/null @@ -1,48 +0,0 @@ -# LSM-Tree 存储引擎 - -BaraDB 的主要存储引擎，使用 Log-Structured Merge-Tree 架构。 - -## 架构 - -``` -┌─────────────────────────────────────────────┐ -│ Writes │ -│ (append to WAL + MemTable) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ MemTable │ -│ (in-memory sorted buffer) │ -└─────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────┐ -│ SSTable │ -│ (sorted string table on disk) │ -└─────────────────────────────────────────────┘ -``` - -## 用法 - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") - -db.put("key1", cast[seq[byte]]("value1")) - -let (found, value) = db.get("key1") - -db.delete("key1") - -db.close() -``` - -## 特性 - -- **写优化**：追加式日志结构 -- **持久性**：WAL 确保崩溃恢复 -- **Bloom Filter**：快速否定查找 -- **压缩**：大小分层策略合并 SSTable -- **页面缓存**：LRU 缓存常用页面 \ No newline at end of file diff --git a/docs/zh/mcp.md b/docs/zh/mcp.md deleted file mode 100644 index e49f45f..0000000 --- a/docs/zh/mcp.md +++ /dev/null @@ -1,109 +0,0 @@ -# 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": "..."}]}} -``` diff --git a/docs/zh/monitoring.md b/docs/zh/monitoring.md deleted file mode 100644 index d09145f..0000000 --- a/docs/zh/monitoring.md +++ /dev/null @@ -1,104 +0,0 @@ -# 监控与可观测性 - -## 健康检查 - -### HTTP 健康端点 - -```bash -curl http://localhost:9470/health -``` - -响应： - -```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 -``` - -服务器准备接受流量时返回 `200 OK`，启动期间返回 `503`。 - -## 指标 - -### Prometheus 兼容指标 - -```bash -curl http://localhost:9470/metrics -``` - -示例输出： - -``` -baradb_queries_total 152340 -baradb_queries_duration_seconds_bucket{le="0.001"} 45000 -baradb_storage_lsm_size_bytes 2147483648 -baradb_cache_hit_rate 0.94 -baradb_active_connections 42 -``` - -### JSON 格式指标 - -```bash -curl http://localhost:9470/metrics?format=json -``` - -## 日志 - -### 日志级别 - -| 级别 | 描述 | -|------|------| -| `debug` | 详细的内部操作 | -| `info` | 正常操作 | -| `warn` | 可恢复的问题 | -| `error` | 需要关注的故障 | - -### 结构化 JSON 日志 - -```bash -BARADB_LOG_LEVEL=info \ -BARADB_LOG_FORMAT=json \ -BARADB_LOG_FILE=/var/log/baradb/baradb.log \ -./build/baradadb -``` - -## Grafana 仪表板 - -导入仪表板 ID `baradb-001` 或使用 `monitoring/grafana-dashboard.json` 中的 JSON。 - -关键面板： -- 每秒查询数 -- 查询延迟百分位数 (p50, p95, p99) -- 存储大小和 SSTable 数量 -- 缓存命中率 -- 活跃连接数 -- 事务率 -- 错误率 - -## 集群监控 - -```bash -curl http://node1:9470/metrics/cluster -``` - -## 使用指标进行故障排除 - -| 症状 | 指标 | 操作 | -|------|------|------| -| 查询慢 | `baradb_queries_duration_seconds` | 检查缓存命中率，考虑添加索引 | -| 内存高 | `process_resident_memory_bytes` | 减小 memtable/cache 大小 | -| 存储增长 | `baradb_storage_lsm_size_bytes` | 运行手动压缩 | -| 连接错误 | `baradb_active_connections` | 增加连接池或添加节点 | \ No newline at end of file diff --git a/docs/zh/performance.md b/docs/zh/performance.md deleted file mode 100644 index 056d28d..0000000 --- a/docs/zh/performance.md +++ /dev/null @@ -1,94 +0,0 @@ -# 性能指南 - -## 基准测试方法论 - -所有基准测试使用： -- **编译器**: Nim 2.2.0 配合 `-d:release --opt:speed` -- **CPU**: AMD Ryzen 9 5900X (12 cores / 24 threads) -- **内存**: 64 GB DDR4-3600 -- **存储**: Samsung 980 Pro NVMe SSD - -```bash -nim c -d:ssl -d:release -r benchmarks/bench_all.nim -``` - -## 存储引擎基准测试 - -### LSM-Tree 键值 - -| 指标 | 值 | -|------|-----| -| 写入吞吐量 | ~580,000 ops/s | -| 读取吞吐量 | ~720,000 ops/s | -| 平均写入延迟 | 1.7 µs | -| 平均读取延迟 | 1.4 µs | - -### B-Tree 索引 - -| 指标 | 值 | -|------|-----| -| 插入吞吐量 | ~1,200,000 ops/s | -| 点查询吞吐量 | ~1,500,000 ops/s | -| 范围扫描 (1000 keys) | ~0.3 ms | - -## 向量引擎基准测试 - -### HNSW 索引 - -| 指标 | 值 | -|------|-----| -| 插入 (dim=128) | ~45,000 vectors/s | -| 搜索 top-10 (n=100K) | ~8 ms | -| 每向量内存 (dim=128) | ~580 bytes | - -参数: `M=16`, `efConstruction=200`, `efSearch=64`。 - -### SIMD 距离函数 - -| 操作 | 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 | - -## 协议基准测试 - -| 协议 | 连接数 | 查询/秒 | 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 | - -## 调优指南 - -### 写密集型工作负载 - -```bash -BARADB_MEMTABLE_SIZE_MB=256 -BARADB_WAL_SYNC_INTERVAL_MS=10 -BARADB_COMPACTION_INTERVAL_MS=30000 -``` - -### 读密集型工作负载 - -```bash -BARADB_CACHE_SIZE_MB=1024 -BARADB_BLOOM_BITS_PER_KEY=10 -BARADB_COMPACTION_INTERVAL_MS=120000 -``` - -### 向量搜索 - -```bash -BARADB_VECTOR_EF_CONSTRUCTION=200 -BARADB_VECTOR_EF_SEARCH=128 -BARADB_VECTOR_M=32 -``` - -### 图分析 - -```bash -BARADB_GRAPH_PAGE_RANK_ITERATIONS=20 -BARADB_GRAPH_LOUVAIN_RESOLUTION=1.0 -``` \ No newline at end of file diff --git a/docs/zh/protocol.md b/docs/zh/protocol.md deleted file mode 100644 index d97d03f..0000000 --- a/docs/zh/protocol.md +++ /dev/null @@ -1,67 +0,0 @@ -# 协议参考 - -BaraDB 支持多种客户端通信协议： -- **Binary Wire Protocol** — 高性能、低延迟 -- **HTTP/REST API** — 语言无关、易于调试 -- **WebSocket** — 流式传输和发布/订阅 - -## Binary Wire Protocol - -所有多字节值使用大端编码。 - -### 连接生命周期 - -``` -Client Server - | | - |─── TCP connect ──────────────>| - |─── Auth message ──────────────>| - |<── Auth_OK / Error ───────────| - |─── Query message ────────────>| - |<── Data / Complete / Error ───| -``` - -### 消息格式 - -``` -┌─────────────┬─────────────┬─────────────┬─────────────────────┐ -│ Length │ Type │ Sequence │ Payload │ -│ (4 bytes) │ (1 byte) │ (1 byte) │ (Length - 6 bytes) │ -└─────────────┴─────────────┴─────────────┴─────────────────────┘ -``` - -### 消息类型 - -| 类型 | ID | 描述 | -|------|----|------| -| Query | 0x01 | 执行查询 | -| Insert | 0x02 | 插入数据 | -| Update | 0x03 | 更新数据 | -| Delete | 0x04 | 删除数据 | -| Ready | 0x05 | 准备就绪 | -| Error | 0x06 | 错误响应 | - -## HTTP/REST API - -Base URL: `http://localhost:9470/api/v1` - -### 端点 - -#### Health - -```http -GET /health -``` - -#### Query - -```http -POST /query -{ - "query": "SELECT * FROM users" -} -``` - -## WebSocket Protocol - -URL: `ws://localhost:9471` \ No newline at end of file diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md deleted file mode 100644 index d87621e..0000000 --- a/docs/zh/quickstart.md +++ /dev/null @@ -1,134 +0,0 @@ -# BaraDB - 快速入门指南 - -## 启动服务器 - -构建 BaraDB 后，启动服务器: - -```bash -./build/baradadb -``` - -服务器默认在 `localhost:9470` 上启动。 - -## 通过 CLI 连接 - -BaraDB 包含一个交互式 shell: - -```bash -./build/baradadb --shell -``` - -## 基本操作 - -### 创建模式 - -```sql -CREATE TYPE Person { - name: str, - age: int32 -}; - -CREATE TYPE Movie { - title: str, - year: int32, - director: Person -}; -``` - -### 插入数据 - -```sql -INSERT Person { name := 'Alice', age := 30 }; -INSERT Person { name := 'Bob', age := 25 }; -``` - -### 查询数据 - -```sql -SELECT name, age FROM Person WHERE age > 18; -``` - -### 更新数据 - -```sql -UPDATE Person SET age = 31 WHERE name = 'Alice'; -``` - -### 删除数据 - -```sql -DELETE FROM Person WHERE name = 'Bob'; -``` - -## 高级查询 - -### JOIN - -```sql -SELECT u.name, o.total -FROM users u -INNER JOIN orders o ON u.id = o.user_id; -``` - -### 聚合 - -```sql -SELECT department, count(*), avg(salary) -FROM employees -GROUP BY department -HAVING count(*) > 5; -``` - -### CTE (公共表表达式) - -```sql -WITH active_users AS ( - SELECT * FROM users WHERE active = true -) -SELECT * FROM active_users; -``` - -## 向量搜索 - -```sql --- 插入向量 -INSERT vectors { id := 1, embedding := [0.1, 0.2, 0.3] }; - --- 搜索相似 -SELECT * FROM vectors ORDER BY cosine_distance(embedding, [0.1, 0.2, 0.3]) LIMIT 10; -``` - -## 图操作 - -```sql --- 匹配图模式 -MATCH (p:Person)-[:KNOWS]->(other:Person) -WHERE p.name = 'Alice' -RETURN other.name; -``` - -## 全文搜索 - -```sql --- 搜索文档 -SELECT * FROM articles WHERE MATCH(title, body) AGAINST('database'); -``` - -## HTTP/REST API - -```bash -# GET 请求 -curl http://localhost:9470/api/users - -# POST 请求 -curl -X POST http://localhost:9470/api/users \ - -H "Content-Type: application/json" \ - -d '{"name": "Alice", "age": 30}' -``` - -## 下一步 - -- [BaraQL 参考](baraql.md) -- [存储引擎](storage.md) -- [架构概述](architecture.md) -- [协议参考](protocol.md) \ No newline at end of file diff --git a/docs/zh/schema.md b/docs/zh/schema.md deleted file mode 100644 index 0ef4d57..0000000 --- a/docs/zh/schema.md +++ /dev/null @@ -1,46 +0,0 @@ -# 模式系统 - -BaraDB 使用 schema-first 设计，支持类型继承和自动迁移。 - -## 定义类型 - -```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) -``` - -## 类型继承 - -```nim -let employee = newType("Employee") -employee.setBases(@["Person"]) -employee.addProperty("department", "str") -s.addType("default", employee) -``` - -## 模式操作 - -### Diff - -```nim -let diff = s.diff(oldSchema, newSchema) -``` - -## 属性类型 - -| 类型 | 描述 | -|------|------| -| `str` | 字符串 | -| `int32` | 32 位整数 | -| `int64` | 64 位整数 | -| `float32` | 32 位浮点数 | -| `float64` | 64 位浮点数 | -| `bool` | 布尔值 | -| `datetime` | 日期/时间 | -| `bytes` | 二进制数据 | \ No newline at end of file diff --git a/docs/zh/security.md b/docs/zh/security.md deleted file mode 100644 index 636b30a..0000000 --- a/docs/zh/security.md +++ /dev/null @@ -1,188 +0,0 @@ -# 安全指南 - -## TLS/SSL 加密 - -BaraDB 支持所有协议的 TLS 1.3（二进制、HTTP、WebSocket）。如果未提供证书，服务器会在启动时自动生成自签名证书以实现零配置加密。 - -### 使用自定义证书 - -```bash -BARADB_TLS_ENABLED=true \ -BARADB_CERT_FILE=/etc/baradb/server.crt \ -BARADB_KEY_FILE=/etc/baradb/server.key \ -./build/baradadb -``` - -### 生成自签名证书 - -```bash -openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \ - -days 365 -nodes -subj "/CN=localhost" -``` - -### Let's Encrypt（生产环境） - -使用 certbot 并将 BaraDB 指向生成的文件： - -```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 -``` - -### 客户端 TLS - -```python -from baradb import Client - -client = Client("localhost", 9472, tls=True, tls_verify=True) -client.connect() -``` - -## 认证 - -### 基于 JWT 的认证 - -BaraDB 使用 HMAC-SHA256 签名的 JWT。 - -#### 启用认证 - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -#### 创建令牌 - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("your-secret-key") -let token = am.createToken(JWTClaims( - sub: "user1", - role: "admin", - exp: getTime() + 24.hours -)) -``` - -#### 基于角色的访问控制 - -| 角色 | 权限 | -|------|------| -| `admin` | 完全访问 | -| `write` | 读取 + 写入 | -| `read` | 只读 | -| `monitor` | 仅指标和健康检查 | - -#### 使用令牌 - -```bash -curl -H "Authorization: Bearer $TOKEN" \ - http://localhost:9470/api/query \ - -d '{"query": "SELECT * FROM users"}' -``` - -```python -from baradb import Client - -client = Client("localhost", 9472) -client.connect() -client.authenticate("eyJhbGciOiJIUzI1NiIs...") -``` - -### 多因素认证 (MFA) - -```nim -import barabadb/protocol/auth - -var am = newAuthManager("secret-key") -let mfaCode = am.generateTOTP("user1") -let valid = am.validateTOTP("user1", mfaCode) -``` - -## 限流 - -Token-bucket 限流防止滥用： - -```nim -import barabadb/protocol/ratelimit - -var rl = newRateLimiter( - rlaTokenBucket, - globalRate = 10000, - perClientRate = 1000, - burstSize = 100 -) - -if not rl.allowRequest("client-ip"): - return error("超出限流") -``` - -## 网络安全 - -### 绑定地址 - -默认 BaraDB 绑定到 `127.0.0.1`（仅本地）。生产环境： - -```bash -BARADB_ADDRESS=0.0.0.0 ./build/baradadb -``` - -### 防火墙规则 - -```bash -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 -sudo ufw deny 9471 -``` - -## 静态数据加密 - -### 操作系统级加密 - -使用 LUKS 进行全磁盘加密： - -```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 -``` - -### 应用级加密 - -```bash -BARADB_STORAGE_ENCRYPTION_KEY="$(openssl rand -hex 32)" \ -./build/baradadb -``` - -## 审计日志 - -```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 -} -``` - -## 安全检查清单 - -- [ ] 更改默认 JWT 密钥 -- [ ] 使用有效证书启用 TLS -- [ ] 绑定到特定接口 -- [ ] 生产环境启用认证 -- [ ] 配置限流 -- [ ] 启用审计日志 -- [ ] 静态数据加密 -- [ ] 以非 root 用户运行 -- [ ] 保持防火墙规则严格 -- [ ] 定期轮换 JWT 密钥 \ No newline at end of file diff --git a/docs/zh/storage.md b/docs/zh/storage.md deleted file mode 100644 index 04e3e53..0000000 --- a/docs/zh/storage.md +++ /dev/null @@ -1,78 +0,0 @@ -# 存储引擎 - -BaraDB 提供多种存储引擎，针对不同的访问模式进行了优化。 - -## LSM-Tree（键值） - -主要的存储引擎，采用写优化的追加式日志结构。 - -### 使用 - -```nim -import barabadb/storage/lsm - -var db = newLSMTree("./data") -db.put("key1", cast[seq[byte]]("value1")) -let (found, value) = db.get("key1") -db.close() -``` - -### 组件 - -- **MemTable**：内存中的排序缓冲区 -- **WAL**：预写日志，用于持久性 -- **SSTable**：磁盘上的排序字符串表 -- **Bloom Filter**：用于快速否定查找的概率结构 -- **Compaction**：带层级管理的大小分层策略 -- **Page Cache**：带命中率追踪的 LRU 缓存 - -## B-Tree 索引 - -用于范围扫描和点查询的有序索引。 - -### 使用 - -```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") -``` - -## 预写日志 (WAL) - -确保写操作的持久性。 - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append("txn1", "SET key1 value1") -wal.flush() -``` - -## Bloom 过滤器 - -用于快速否定查找的概率数据结构。 - -```nim -import barabadb/storage/bloom - -var filter = newBloomFilter(10000, 0.01) -filter.add("key1") -if filter.mightContain("key1"): - echo "可能存在" -``` - -## 内存映射 I/O - -使用 mmap 进行高效的文件访问。 - -```nim -import barabadb/storage/mmap - -var mapped = mmapFile("./data/file.dat") -let data = mapped.read(0, 100) -``` \ No newline at end of file diff --git a/docs/zh/transactions.md b/docs/zh/transactions.md deleted file mode 100644 index 9fefcda..0000000 --- a/docs/zh/transactions.md +++ /dev/null @@ -1,77 +0,0 @@ -# 事务与 MVCC - -MVCC（多版本并发控制），提供快照隔离和死锁检测。 - -## 使用 - -```nim -import barabadb/core/mvcc - -var tm = newTxnManager() -let txn = tm.beginTxn() - -# 写操作 -discard tm.write(txn, "key1", cast[seq[byte]]("value1")) -discard tm.write(txn, "key2", cast[seq[byte]]("value2")) - -# 保存点 -tm.savepoint(txn) -discard tm.write(txn, "key3", cast[seq[byte]]("value3")) -discard tm.rollbackToSavepoint(txn) - -# 提交 -discard tm.commit(txn) -``` - -## 事务隔离 - -BaraDB 使用**快照隔离**： -- 读取者不阻塞写入者 -- 写入者不阻塞读取者 -- 每个事务看到一致的快照 - -## 死锁检测 - -```nim -import barabadb/core/deadlock - -var detector = newDeadlockDetector() -if detector.detectCycle(txn1, txn2): - echo "检测到死锁！" -``` - -## 预写日志 - -```nim -import barabadb/storage/wal - -var wal = newWAL("./wal") -wal.append(txnId, "SET key value") -wal.flush() -``` - -## 保存点 - -嵌套事务保存点： - -```nim -tm.savepoint(txn, "sp1") -tm.rollbackToSavepoint(txn, "sp1") -``` - -## 形式化验证 - -MVCC/快照隔离协议在 TLA+ 中形式化规范： - -- **规范：** `formal-verification/mvcc.tla` -- **验证的属性：** - - `NoDirtyReads` — 事务从不读取未提交的数据 - - `ReadOwnWrites` — 事务总是看到自己的写入 - - `WriteWriteConflict` — 先提交者胜出 - -本地运行 TLC： - -```bash -cd formal-verification -java -cp tla2tools.jar tlc2.TLC -config models/mvcc.cfg mvcc.tla -``` \ No newline at end of file diff --git a/docs/zh/troubleshooting.md b/docs/zh/troubleshooting.md deleted file mode 100644 index 388697b..0000000 --- a/docs/zh/troubleshooting.md +++ /dev/null @@ -1,118 +0,0 @@ -# 故障排除指南 - -## 安装问题 - -### 未找到 Nim - -```bash -curl https://nim-lang.org/choosenim/init.sh -sSf | sh -``` - -### SSL 编译错误 - -```bash -nim c -d:ssl -d:release -o:build/baradadb src/baradadb.nim -``` - -### 缺少依赖 - -```bash -nimble install -d -y -``` - -## 运行时问题 - -### 端口已被占用 - -```bash -BARADB_PORT=5433 ./build/baradadb -lsof -ti:9472 | xargs kill -9 -``` - -### 权限被拒绝 - -```bash -mkdir -p ./data -chmod 755 ./data -``` - -### 内存不足 - -```bash -BARADB_MEMTABLE_SIZE_MB=32 \ -BARADB_CACHE_SIZE_MB=128 \ -BARADB_VECTOR_EF_CONSTRUCTION=100 \ -./build/baradadb -``` - -### 磁盘已满 - -```bash -curl -X POST http://localhost:9470/api/admin/compact -./build/baradadb --compact -``` - -## 查询问题 - -### 语法错误 - -```sql -SELECT name, age FROM users WHERE age > 18; -``` - -### 表未找到 - -```sql -CREATE TYPE User { name: str, age: int32 }; -``` - -### 类型不匹配 - -```sql -SELECT * FROM users WHERE age > 18; -``` - -## 连接问题 - -### 连接被拒绝 - -```bash -./build/baradadb -sudo ufw allow 9472 -``` - -### 认证失败 - -```bash -BARADB_AUTH_ENABLED=true \ -BARADB_JWT_SECRET="correct-secret" \ -./build/baradadb -``` - -## 性能问题 - -### 查询慢 - -1. 创建索引：`CREATE INDEX idx_users_name ON users(name);` -2. 使用 LIMIT -3. 增加缓存：`BARADB_CACHE_SIZE_MB=1024` - -### 高 CPU 使用率 - -```bash -BARADB_COMPACTION_INTERVAL_MS=300000 ./build/baradadb -``` - -### 高内存使用 - -```bash -BARADB_MEMTABLE_SIZE_MB=64 -BARADB_CACHE_SIZE_MB=256 -BARADB_VECTOR_M=8 -``` - -## 调试模式 - -```bash -BARADB_LOG_LEVEL=debug ./build/baradadb -``` \ No newline at end of file diff --git a/docs/zh/udf.md b/docs/zh/udf.md deleted file mode 100644 index 30a55f7..0000000 --- a/docs/zh/udf.md +++ /dev/null @@ -1,47 +0,0 @@ -# 用户定义函数 - -使用自定义函数扩展 BaraQL。 - -## 用法 - -```nim -import barabadb/query/udf - -var reg = newUDFRegistry() - -reg.registerStdlib() - -reg.register("greet", @[UDFParam(name: "name", typeName: "str")], - "str", proc(args: seq[Value]): Value = - return Value(kind: vkString, strVal: "Hello, " & args[0].strVal & "!")) -``` - -## 标准库函数 - -| 函数 | 描述 | 示例 | -|------|------|------| -| `abs(n)` | 绝对值 | `abs(-5)` → 5 | -| `sqrt(n)` | 平方根 | `sqrt(16)` → 4 | -| `pow(n, e)` | 幂 | `pow(2, 3)` → 8 | -| `lower(s)` | 小写 | `lower('ABC')` → 'abc' | -| `upper(s)` | 大写 | `upper('abc')` → 'ABC' | -| `len(s)` | 长度 | `len('hello')` → 5 | -| `trim(s)` | 去空格 | `trim(' hello ')` → 'hello' | - -## 注册函数 - -```nim -reg.register( - name: "my_function", - params: @[UDFParam(name: "arg1", typeName: "str")], - returnType: "str", - body: proc(args: seq[Value]): Value = - result = Value(kind: vkString, strVal: "") -) -``` - -## 在查询中使用 UDF - -```sql -SELECT greet(name) FROM users; -``` \ No newline at end of file diff --git a/docs/zh/vector.md b/docs/zh/vector.md deleted file mode 100644 index 2c850db..0000000 --- a/docs/zh/vector.md +++ /dev/null @@ -1,65 +0,0 @@ -# 向量搜索引擎 - -用于相似性搜索的本机 HNSW 和 IVF-PQ 索引。 - -## 用法 - -```nim -import barabadb/vector/engine - -var idx = newHNSWIndex(dimensions = 128) -idx.insert(1, @[1.0'f32, 0.0'f32, ...], {"category": "A"}.toTable) - -let results = idx.search(queryVector, k = 10) -``` - -## 索引类型 - -### HNSW - -用于近似最近邻搜索的分层可导航小世界图。 - -```nim -var hnsw = newHNSWIndex( - dimensions = 128, - m = 16, - efConstruction = 200, - efSearch = 100 -) -``` - -### IVF-PQ - -带乘积量化的倒排文件索引。 - -```nim -var ivfpq = newIVFPQIndex( - dimensions = 128, - numCentroids = 256, - subQuantizers = 8 -) -``` - -## 距离度量 - -| 度量 | 描述 | -|------|------| -| `cosine` | 余弦相似度 | -| `euclidean` | L2 距离 | -| `dotproduct` | 点积相似度 | -| `manhattan` | L1 距离 | - -## 量化 - -```nim -let scalar = scalarQuantize(data, bits = 8) -let pq = productQuantize(data, subVectors = 8, bits = 8) -``` - -## SIMD 加速 - -```nim -import barabadb/vector/simd - -let dist = simdCosineDistance(vec1, vec2) -``` \ No newline at end of file