From e9d3c7e9de2134e190bd616dcc436feb1277e60c Mon Sep 17 00:00:00 2001 From: dimgigov Date: Thu, 7 May 2026 23:42:55 +0300 Subject: [PATCH] docs: add multi-language documentation (ru, fa, zh, tr, ar) --- README.md | 5 + 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 | 101 ++++++++ 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 | 62 +++++ docs/ar/lsm.md | 48 ++++ 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/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 | 492 +++++++++++++++++++++++++++++++++++++ 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/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 | 5 + 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 | 492 +++++++++++++++++++++++++++++++++++++ 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/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 | 110 +++++++++ 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 | 62 +++++ docs/tr/lsm.md | 48 ++++ 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 | 492 +++++++++++++++++++++++++++++++++++++ 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/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 +++++ 157 files changed, 14339 insertions(+) create mode 100644 docs/ar/api-binary.md create mode 100644 docs/ar/api-http.md create mode 100644 docs/ar/api-websocket.md create mode 100644 docs/ar/architecture.md create mode 100644 docs/ar/backup.md create mode 100644 docs/ar/baraql.md create mode 100644 docs/ar/btree.md create mode 100644 docs/ar/changelog.md create mode 100644 docs/ar/clients.md create mode 100644 docs/ar/columnar.md create mode 100644 docs/ar/configuration.md create mode 100644 docs/ar/crossmodal.md create mode 100644 docs/ar/deployment.md create mode 100644 docs/ar/distributed.md create mode 100644 docs/ar/docker.md create mode 100644 docs/ar/fts.md create mode 100644 docs/ar/graph.md create mode 100644 docs/ar/index.md create mode 100644 docs/ar/installation.md create mode 100644 docs/ar/lsm.md create mode 100644 docs/ar/monitoring.md create mode 100644 docs/ar/performance.md create mode 100644 docs/ar/protocol.md create mode 100644 docs/ar/quickstart.md create mode 100644 docs/ar/schema.md create mode 100644 docs/ar/security.md create mode 100644 docs/ar/storage.md create mode 100644 docs/ar/transactions.md create mode 100644 docs/ar/troubleshooting.md create mode 100644 docs/ar/udf.md create mode 100644 docs/ar/vector.md create mode 100644 docs/fa/api-binary.md create mode 100644 docs/fa/api-http.md create mode 100644 docs/fa/api-websocket.md create mode 100644 docs/fa/architecture.md create mode 100644 docs/fa/backup.md create mode 100644 docs/fa/baraql.md create mode 100644 docs/fa/btree.md create mode 100644 docs/fa/changelog.md create mode 100644 docs/fa/clients.md create mode 100644 docs/fa/columnar.md create mode 100644 docs/fa/configuration.md create mode 100644 docs/fa/crossmodal.md create mode 100644 docs/fa/deployment.md create mode 100644 docs/fa/distributed.md create mode 100644 docs/fa/docker.md create mode 100644 docs/fa/fts.md create mode 100644 docs/fa/graph.md create mode 100644 docs/fa/index.md create mode 100644 docs/fa/installation.md create mode 100644 docs/fa/lsm.md create mode 100644 docs/fa/monitoring.md create mode 100644 docs/fa/performance.md create mode 100644 docs/fa/protocol.md create mode 100644 docs/fa/quickstart.md create mode 100644 docs/fa/schema.md create mode 100644 docs/fa/security.md create mode 100644 docs/fa/storage.md create mode 100644 docs/fa/transactions.md create mode 100644 docs/fa/troubleshooting.md create mode 100644 docs/fa/udf.md create mode 100644 docs/fa/vector.md create mode 100644 docs/ru/api-binary.md create mode 100644 docs/ru/api-http.md create mode 100644 docs/ru/api-websocket.md create mode 100644 docs/ru/architecture.md create mode 100644 docs/ru/backup.md create mode 100644 docs/ru/baraql.md create mode 100644 docs/ru/btree.md create mode 100644 docs/ru/changelog.md create mode 100644 docs/ru/clients.md create mode 100644 docs/ru/columnar.md create mode 100644 docs/ru/configuration.md create mode 100644 docs/ru/crossmodal.md create mode 100644 docs/ru/deployment.md create mode 100644 docs/ru/distributed.md create mode 100644 docs/ru/docker.md create mode 100644 docs/ru/fts.md create mode 100644 docs/ru/graph.md create mode 100644 docs/ru/index.md create mode 100644 docs/ru/installation.md create mode 100644 docs/ru/lsm.md create mode 100644 docs/ru/monitoring.md create mode 100644 docs/ru/performance.md create mode 100644 docs/ru/protocol.md create mode 100644 docs/ru/quickstart.md create mode 100644 docs/ru/schema.md create mode 100644 docs/ru/security.md create mode 100644 docs/ru/storage.md create mode 100644 docs/ru/transactions.md create mode 100644 docs/ru/troubleshooting.md create mode 100644 docs/ru/udf.md create mode 100644 docs/ru/vector.md create mode 100644 docs/tr/api-binary.md create mode 100644 docs/tr/api-http.md create mode 100644 docs/tr/api-websocket.md create mode 100644 docs/tr/architecture.md create mode 100644 docs/tr/backup.md create mode 100644 docs/tr/baraql.md create mode 100644 docs/tr/btree.md create mode 100644 docs/tr/changelog.md create mode 100644 docs/tr/clients.md create mode 100644 docs/tr/columnar.md create mode 100644 docs/tr/configuration.md create mode 100644 docs/tr/crossmodal.md create mode 100644 docs/tr/deployment.md create mode 100644 docs/tr/distributed.md create mode 100644 docs/tr/docker.md create mode 100644 docs/tr/fts.md create mode 100644 docs/tr/graph.md create mode 100644 docs/tr/index.md create mode 100644 docs/tr/installation.md create mode 100644 docs/tr/lsm.md create mode 100644 docs/tr/monitoring.md create mode 100644 docs/tr/performance.md create mode 100644 docs/tr/protocol.md create mode 100644 docs/tr/quickstart.md create mode 100644 docs/tr/schema.md create mode 100644 docs/tr/security.md create mode 100644 docs/tr/storage.md create mode 100644 docs/tr/transactions.md create mode 100644 docs/tr/troubleshooting.md create mode 100644 docs/tr/udf.md create mode 100644 docs/tr/vector.md create mode 100644 docs/zh/api-binary.md create mode 100644 docs/zh/api-http.md create mode 100644 docs/zh/api-websocket.md create mode 100644 docs/zh/architecture.md create mode 100644 docs/zh/backup.md create mode 100644 docs/zh/baraql.md create mode 100644 docs/zh/btree.md create mode 100644 docs/zh/changelog.md create mode 100644 docs/zh/clients.md create mode 100644 docs/zh/columnar.md create mode 100644 docs/zh/configuration.md create mode 100644 docs/zh/crossmodal.md create mode 100644 docs/zh/deployment.md create mode 100644 docs/zh/distributed.md create mode 100644 docs/zh/docker.md create mode 100644 docs/zh/fts.md create mode 100644 docs/zh/graph.md create mode 100644 docs/zh/index.md create mode 100644 docs/zh/installation.md create mode 100644 docs/zh/lsm.md create mode 100644 docs/zh/monitoring.md create mode 100644 docs/zh/performance.md create mode 100644 docs/zh/protocol.md create mode 100644 docs/zh/quickstart.md create mode 100644 docs/zh/schema.md create mode 100644 docs/zh/security.md create mode 100644 docs/zh/storage.md create mode 100644 docs/zh/transactions.md create mode 100644 docs/zh/troubleshooting.md create mode 100644 docs/zh/udf.md create mode 100644 docs/zh/vector.md diff --git a/README.md b/README.md index b53cb6f..86582f6 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,11 @@ **A multimodal database engine written in Nim — 100% native, zero dependencies.** [![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](baradadb.nimble) +[![Documentation](https://img.shields.io/badge/docs-7_languages-blue.svg)](docs/index.md) + +## Documentation + +📖 **[Read the documentation in your language](docs/index.md)** — English, Български, Русский, فارسی, 中文, Türkçe, العربية 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 diff --git a/docs/ar/api-binary.md b/docs/ar/api-binary.md new file mode 100644 index 0000000..1516416 --- /dev/null +++ b/docs/ar/api-binary.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..68f194d --- /dev/null +++ b/docs/ar/api-http.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..b4370ea --- /dev/null +++ b/docs/ar/api-websocket.md @@ -0,0 +1,78 @@ +# 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 new file mode 100644 index 0000000..09022c3 --- /dev/null +++ b/docs/ar/architecture.md @@ -0,0 +1,102 @@ +# بنية 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 new file mode 100644 index 0000000..b34aac9 --- /dev/null +++ b/docs/ar/backup.md @@ -0,0 +1,82 @@ +# النسخ الاحتياطي والاستعادة + +## لقطات عبر الإنترنت + +تدعم 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 new file mode 100644 index 0000000..a521b6e --- /dev/null +++ b/docs/ar/baraql.md @@ -0,0 +1,101 @@ +# مرجع لغة استعلام 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 }; +COMMIT; +``` \ No newline at end of file diff --git a/docs/ar/btree.md b/docs/ar/btree.md new file mode 100644 index 0000000..48152ae --- /dev/null +++ b/docs/ar/btree.md @@ -0,0 +1,26 @@ +# فهرس 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 new file mode 100644 index 0000000..7abea55 --- /dev/null +++ b/docs/ar/changelog.md @@ -0,0 +1,76 @@ +# سجل التغييرات + +## [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 new file mode 100644 index 0000000..a7ac77f --- /dev/null +++ b/docs/ar/clients.md @@ -0,0 +1,66 @@ +# حزم العملاء + +توفر 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 new file mode 100644 index 0000000..246c5e9 --- /dev/null +++ b/docs/ar/columnar.md @@ -0,0 +1,50 @@ +# التخزين العمودي + +تخزين موجهة للأعمدة للاستعلامات التحليلية والتجميعات. + +## الاستخدام + +```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 new file mode 100644 index 0000000..c824355 --- /dev/null +++ b/docs/ar/configuration.md @@ -0,0 +1,96 @@ +# مرجع التكوين + +يمكن تكوين 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 new file mode 100644 index 0000000..8f35cec --- /dev/null +++ b/docs/ar/crossmodal.md @@ -0,0 +1,48 @@ +# الاستعلامات عبر الأنماط + +القدرة الفريدة لـ 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 new file mode 100644 index 0000000..6f4d181 --- /dev/null +++ b/docs/ar/deployment.md @@ -0,0 +1,68 @@ +# دليل النشر + +## 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 new file mode 100644 index 0000000..fa845d5 --- /dev/null +++ b/docs/ar/distributed.md @@ -0,0 +1,73 @@ +# الأنظمة الموزعة + +تدعم 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 new file mode 100644 index 0000000..2147929 --- /dev/null +++ b/docs/ar/docker.md @@ -0,0 +1,78 @@ +# دليل نشر Docker + +## البداية السريعة + +```bash +git clone https://github.com/katehonz/barabaDB.git +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 new file mode 100644 index 0000000..c55d9c0 --- /dev/null +++ b/docs/ar/fts.md @@ -0,0 +1,47 @@ +# محرك البحث النصي الكامل + +فهرس مقلوب مع ترتيب 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 new file mode 100644 index 0000000..75afed5 --- /dev/null +++ b/docs/ar/graph.md @@ -0,0 +1,42 @@ +# محرك الرسم البياني + +تخزين قائمة المجاورة مع خوارزميات مدمجة للعبور والتحليل. + +## الاستخدام + +```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 new file mode 100644 index 0000000..eaa2cc8 --- /dev/null +++ b/docs/ar/index.md @@ -0,0 +1,59 @@ +# توثيق 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 new file mode 100644 index 0000000..dc37792 --- /dev/null +++ b/docs/ar/installation.md @@ -0,0 +1,62 @@ +# دليل تثبيت 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 +``` + +### macOS + +```bash +brew install nim +``` + +### ويندوز + +```powershell +winget install nim +``` + +## بناء BaraDB + +```bash +git clone https://github.com/katehonz/barabaDB.git +cd barabaDB +nimble install -d -y +nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim +``` + +## التشغيل الأول + +```bash +./build/baradadb +curl http://localhost:9470/health +./build/baradadb --shell +``` + +## الخطوات التالية + +- [دليل البداية السريعة](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 new file mode 100644 index 0000000..7a7ef5d --- /dev/null +++ b/docs/ar/lsm.md @@ -0,0 +1,48 @@ +# محرك تخزين 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/monitoring.md b/docs/ar/monitoring.md new file mode 100644 index 0000000..390a207 --- /dev/null +++ b/docs/ar/monitoring.md @@ -0,0 +1,84 @@ +# المراقبة والقابلية للملاحظة + +## فحوصات الصحة + +### نقطة نهاية صحة 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 new file mode 100644 index 0000000..0c4f463 --- /dev/null +++ b/docs/ar/performance.md @@ -0,0 +1,68 @@ +# دليل الأداء + +## منهجية المعايير + +جميع المعايير تعمل بـ: +- **المترجم**: 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 new file mode 100644 index 0000000..537221b --- /dev/null +++ b/docs/ar/protocol.md @@ -0,0 +1,67 @@ +# مرجع البروتوكول + +يدعم 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 new file mode 100644 index 0000000..8cab283 --- /dev/null +++ b/docs/ar/quickstart.md @@ -0,0 +1,99 @@ +# دليل البداية السريعة لـ 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 new file mode 100644 index 0000000..cf7fe63 --- /dev/null +++ b/docs/ar/schema.md @@ -0,0 +1,46 @@ +# نظام المخطط + +يستخدم 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 new file mode 100644 index 0000000..acb6b7e --- /dev/null +++ b/docs/ar/security.md @@ -0,0 +1,76 @@ +# دليل الأمان + +## تشفير 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 new file mode 100644 index 0000000..5f73d4b --- /dev/null +++ b/docs/ar/storage.md @@ -0,0 +1,67 @@ +# محركات التخزين + +توفر 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 new file mode 100644 index 0000000..2d2a3b5 --- /dev/null +++ b/docs/ar/transactions.md @@ -0,0 +1,47 @@ +# المعاملات و 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 new file mode 100644 index 0000000..5ff728a --- /dev/null +++ b/docs/ar/troubleshooting.md @@ -0,0 +1,81 @@ +# دليل حل المشكلات + +## مشاكل التثبيت + +### 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 new file mode 100644 index 0000000..5f22b9b --- /dev/null +++ b/docs/ar/udf.md @@ -0,0 +1,47 @@ +# الدوال المحددة من المستخدم + +توسيع 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 new file mode 100644 index 0000000..e72609d --- /dev/null +++ b/docs/ar/vector.md @@ -0,0 +1,65 @@ +# محرك البحث المتجهي + +فهارس 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/fa/api-binary.md b/docs/fa/api-binary.md new file mode 100644 index 0000000..30d039c --- /dev/null +++ b/docs/fa/api-binary.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..94c8478 --- /dev/null +++ b/docs/fa/api-http.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..340bc9c --- /dev/null +++ b/docs/fa/api-websocket.md @@ -0,0 +1,67 @@ +# 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 new file mode 100644 index 0000000..47b3d08 --- /dev/null +++ b/docs/fa/architecture.md @@ -0,0 +1,197 @@ +# معماری 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 new file mode 100644 index 0000000..7093bc0 --- /dev/null +++ b/docs/fa/backup.md @@ -0,0 +1,81 @@ +# پشتیبان‌گیری و بازیابی + +## 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 new file mode 100644 index 0000000..f45be04 --- /dev/null +++ b/docs/fa/baraql.md @@ -0,0 +1,492 @@ +# مرجع زبان پرس‌وجو 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; +``` \ No newline at end of file diff --git a/docs/fa/btree.md b/docs/fa/btree.md new file mode 100644 index 0000000..af6bc22 --- /dev/null +++ b/docs/fa/btree.md @@ -0,0 +1,25 @@ +# اندیس 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 new file mode 100644 index 0000000..1e055b4 --- /dev/null +++ b/docs/fa/changelog.md @@ -0,0 +1,70 @@ +# سیاهه تغییرات + +## [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 new file mode 100644 index 0000000..dac3ac2 --- /dev/null +++ b/docs/fa/clients.md @@ -0,0 +1,66 @@ +# 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 new file mode 100644 index 0000000..ec67458 --- /dev/null +++ b/docs/fa/columnar.md @@ -0,0 +1,50 @@ +# ذخیره‌سازی ستونی + +ذخیره‌سازی ستون-محور برای کوئری‌های تحلیلی و تجمیع‌ها. + +## استفاده + +```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 new file mode 100644 index 0000000..f3488c2 --- /dev/null +++ b/docs/fa/configuration.md @@ -0,0 +1,94 @@ +# مرجع پیکربندی + +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 new file mode 100644 index 0000000..20dfd43 --- /dev/null +++ b/docs/fa/crossmodal.md @@ -0,0 +1,40 @@ +# پرس‌وجوهای بین‌حالتی + +توانایی منحصربه‌فرد 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 new file mode 100644 index 0000000..d549545 --- /dev/null +++ b/docs/fa/deployment.md @@ -0,0 +1,249 @@ +# راهنمای استقرار 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 new file mode 100644 index 0000000..254589f --- /dev/null +++ b/docs/fa/distributed.md @@ -0,0 +1,82 @@ +# سیستم‌های توزیع‌شده + +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 new file mode 100644 index 0000000..09cda9f --- /dev/null +++ b/docs/fa/docker.md @@ -0,0 +1,113 @@ +# راهنمای استقرار Docker + +## شروع سریع + +```bash +git clone https://github.com/katehonz/barabaDB.git +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 new file mode 100644 index 0000000..cbbe755 --- /dev/null +++ b/docs/fa/fts.md @@ -0,0 +1,47 @@ +# موتور جستجوی تمام‌متن + +اندیس معکوس با رتبه‌بندی 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 new file mode 100644 index 0000000..25a650f --- /dev/null +++ b/docs/fa/graph.md @@ -0,0 +1,42 @@ +# موتور گراف + +ذخیره‌سازی لیست مجاورت با الگوریتم‌های داخلی برای پیمایش و تحلیل گراف. + +## استفاده + +```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 new file mode 100644 index 0000000..0ab1e17 --- /dev/null +++ b/docs/fa/index.md @@ -0,0 +1,59 @@ +# مستندات 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 new file mode 100644 index 0000000..99d5ea0 --- /dev/null +++ b/docs/fa/installation.md @@ -0,0 +1,309 @@ +# راهنمای نصب 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://github.com/katehonz/barabaDB.git +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 v0.1.0 — 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 v0.1.0 — 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 new file mode 100644 index 0000000..cf4c097 --- /dev/null +++ b/docs/fa/lsm.md @@ -0,0 +1,48 @@ +# موتور ذخیره‌سازی 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/monitoring.md b/docs/fa/monitoring.md new file mode 100644 index 0000000..0b42716 --- /dev/null +++ b/docs/fa/monitoring.md @@ -0,0 +1,78 @@ +# پایش و مشاهده‌پذیری + +## بررسی‌های سلامت + +### 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 new file mode 100644 index 0000000..a466cef --- /dev/null +++ b/docs/fa/performance.md @@ -0,0 +1,62 @@ +# راهنمای عملکرد + +## روش‌شناسی بنچمارک + +همه بنچمارک‌ها با 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 new file mode 100644 index 0000000..a900a1f --- /dev/null +++ b/docs/fa/protocol.md @@ -0,0 +1,67 @@ +# مرجع پروتکل + +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 new file mode 100644 index 0000000..b1a5766 --- /dev/null +++ b/docs/fa/quickstart.md @@ -0,0 +1,134 @@ +# راهنمای شروع سریع 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 new file mode 100644 index 0000000..654d7aa --- /dev/null +++ b/docs/fa/schema.md @@ -0,0 +1,46 @@ +# سیستم طرحواره + +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 new file mode 100644 index 0000000..df0657c --- /dev/null +++ b/docs/fa/security.md @@ -0,0 +1,120 @@ +# راهنمای امنیت + +## رمزنگاری 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 new file mode 100644 index 0000000..d24fafb --- /dev/null +++ b/docs/fa/storage.md @@ -0,0 +1,78 @@ +# موتورهای ذخیره‌سازی + +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 new file mode 100644 index 0000000..06be083 --- /dev/null +++ b/docs/fa/transactions.md @@ -0,0 +1,67 @@ +# تراکنش‌ها و 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 new file mode 100644 index 0000000..25b6134 --- /dev/null +++ b/docs/fa/troubleshooting.md @@ -0,0 +1,87 @@ +# عیب‌یابی + +## مشکلات نصب + +### 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 new file mode 100644 index 0000000..da4f1eb --- /dev/null +++ b/docs/fa/udf.md @@ -0,0 +1,46 @@ +# توابع تعریف‌شده کاربر + +گسترش 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 new file mode 100644 index 0000000..a15056a --- /dev/null +++ b/docs/fa/vector.md @@ -0,0 +1,57 @@ +# موتور جستجوی برداری + +اندیس‌های 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 7eeab62..2187f06 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,11 @@ - [English](en/) - [Български (Bulgarian)](bg/) +- [Русский (Russian)](ru/) +- [فارسی (Farsi)](fa/) +- [中文 (Chinese)](zh/) +- [Türkçe (Turkish)](tr/) +- [العربية (Arabic)](ar/) --- diff --git a/docs/ru/api-binary.md b/docs/ru/api-binary.md new file mode 100644 index 0000000..90ae6b6 --- /dev/null +++ b/docs/ru/api-binary.md @@ -0,0 +1,71 @@ +# 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 new file mode 100644 index 0000000..315c5a3 --- /dev/null +++ b/docs/ru/api-http.md @@ -0,0 +1,83 @@ +# 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 new file mode 100644 index 0000000..5de56b8 --- /dev/null +++ b/docs/ru/api-websocket.md @@ -0,0 +1,80 @@ +# 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 new file mode 100644 index 0000000..5c4cb70 --- /dev/null +++ b/docs/ru/architecture.md @@ -0,0 +1,197 @@ +# Архитектура 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 new file mode 100644 index 0000000..2232fbd --- /dev/null +++ b/docs/ru/backup.md @@ -0,0 +1,120 @@ +# Резервное копирование и восстановление + +## Онлайн снэпшоты + +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 new file mode 100644 index 0000000..ede4eff --- /dev/null +++ b/docs/ru/baraql.md @@ -0,0 +1,492 @@ +# Справочник по языку запросов 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; +``` \ No newline at end of file diff --git a/docs/ru/btree.md b/docs/ru/btree.md new file mode 100644 index 0000000..5fe6eff --- /dev/null +++ b/docs/ru/btree.md @@ -0,0 +1,34 @@ +# 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 new file mode 100644 index 0000000..6b2e386 --- /dev/null +++ b/docs/ru/changelog.md @@ -0,0 +1,78 @@ +# История изменений + +Все важные изменения в 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 new file mode 100644 index 0000000..2248049 --- /dev/null +++ b/docs/ru/clients.md @@ -0,0 +1,82 @@ +# Клиентские 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 new file mode 100644 index 0000000..b246e84 --- /dev/null +++ b/docs/ru/columnar.md @@ -0,0 +1,58 @@ +# Колоночное хранилище + +Хранилище с ориентацией на столбцы для аналитических запросов и агрегаций. + +## Использование + +```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 new file mode 100644 index 0000000..3fb993d --- /dev/null +++ b/docs/ru/configuration.md @@ -0,0 +1,217 @@ +# Справочник по конфигурации 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 v0.1.0 — 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 new file mode 100644 index 0000000..41c94bf --- /dev/null +++ b/docs/ru/crossmodal.md @@ -0,0 +1,63 @@ +# Кросс-модальные запросы + +Уникальная возможность 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 new file mode 100644 index 0000000..e8f605d --- /dev/null +++ b/docs/ru/deployment.md @@ -0,0 +1,44 @@ +# Руководство по развёртыванию + +## 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 new file mode 100644 index 0000000..7349ec8 --- /dev/null +++ b/docs/ru/distributed.md @@ -0,0 +1,108 @@ +# Распределённые системы + +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 new file mode 100644 index 0000000..b409688 --- /dev/null +++ b/docs/ru/docker.md @@ -0,0 +1,189 @@ +# Руководство по развёртыванию Docker + +## Быстрый старт + +```bash +# Клонировать репозиторий +git clone https://github.com/katehonz/barabaDB.git +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 new file mode 100644 index 0000000..b2397b7 --- /dev/null +++ b/docs/ru/fts.md @@ -0,0 +1,62 @@ +# Полнотекстовый поиск + +Инвертированный индекс с ранжированием 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 new file mode 100644 index 0000000..b6cdffd --- /dev/null +++ b/docs/ru/graph.md @@ -0,0 +1,51 @@ +# Графовый движок + +Хранение в виде списка смежности со встроенными алгоритмами для обходов и анализа графов. + +## Использование + +```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 new file mode 100644 index 0000000..a7754c3 --- /dev/null +++ b/docs/ru/index.md @@ -0,0 +1,59 @@ +# 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 new file mode 100644 index 0000000..122b66e --- /dev/null +++ b/docs/ru/installation.md @@ -0,0 +1,309 @@ +# 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://github.com/katehonz/barabaDB.git +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 v0.1.0 — 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 v0.1.0 — 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 new file mode 100644 index 0000000..4a7d539 --- /dev/null +++ b/docs/ru/lsm.md @@ -0,0 +1,61 @@ +# 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/monitoring.md b/docs/ru/monitoring.md new file mode 100644 index 0000000..407a7ec --- /dev/null +++ b/docs/ru/monitoring.md @@ -0,0 +1,148 @@ +# Мониторинг и наблюдаемость + +## Проверки здоровья + +### 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 new file mode 100644 index 0000000..93bd712 --- /dev/null +++ b/docs/ru/performance.md @@ -0,0 +1,95 @@ +# Руководство по производительности + +## Методология бенчмаркинга + +Все бенчмарки запускаются с: +- **Компилятор**: 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 new file mode 100644 index 0000000..9cb61cf --- /dev/null +++ b/docs/ru/protocol.md @@ -0,0 +1,87 @@ +# Справочник по протоколу + +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 new file mode 100644 index 0000000..d05ba97 --- /dev/null +++ b/docs/ru/quickstart.md @@ -0,0 +1,134 @@ +# 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 new file mode 100644 index 0000000..96303c2 --- /dev/null +++ b/docs/ru/schema.md @@ -0,0 +1,52 @@ +# Система схем + +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 new file mode 100644 index 0000000..e769527 --- /dev/null +++ b/docs/ru/security.md @@ -0,0 +1,210 @@ +# Руководство по безопасности + +## 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 new file mode 100644 index 0000000..9322e6a --- /dev/null +++ b/docs/ru/storage.md @@ -0,0 +1,78 @@ +# Хранилища данных + +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 new file mode 100644 index 0000000..481157a --- /dev/null +++ b/docs/ru/transactions.md @@ -0,0 +1,78 @@ +# Транзакции и 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 new file mode 100644 index 0000000..7350e42 --- /dev/null +++ b/docs/ru/troubleshooting.md @@ -0,0 +1,168 @@ +# Руководство по устранению проблем + +## Проблемы с установкой + +### 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 new file mode 100644 index 0000000..41ba222 --- /dev/null +++ b/docs/ru/udf.md @@ -0,0 +1,51 @@ +# Пользовательские функции + +Расширение 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 new file mode 100644 index 0000000..33936fc --- /dev/null +++ b/docs/ru/vector.md @@ -0,0 +1,71 @@ +# Векторный движок + +Родные индексы 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 new file mode 100644 index 0000000..141a4b3 --- /dev/null +++ b/docs/tr/api-binary.md @@ -0,0 +1,62 @@ +# İ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 new file mode 100644 index 0000000..dfeae83 --- /dev/null +++ b/docs/tr/api-http.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..af085a7 --- /dev/null +++ b/docs/tr/api-websocket.md @@ -0,0 +1,78 @@ +# 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 new file mode 100644 index 0000000..542b77e --- /dev/null +++ b/docs/tr/architecture.md @@ -0,0 +1,102 @@ +# 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 new file mode 100644 index 0000000..69bcc49 --- /dev/null +++ b/docs/tr/backup.md @@ -0,0 +1,82 @@ +# 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 new file mode 100644 index 0000000..261d4b7 --- /dev/null +++ b/docs/tr/baraql.md @@ -0,0 +1,110 @@ +# 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 }; +COMMIT; +``` + +## Grafik Kalıpları + +```sql +MATCH (p:Person)-[:KNOWS]->(friend:Person) +WHERE p.name = 'Alice' +RETURN friend.name; +``` \ No newline at end of file diff --git a/docs/tr/btree.md b/docs/tr/btree.md new file mode 100644 index 0000000..d95ae7e --- /dev/null +++ b/docs/tr/btree.md @@ -0,0 +1,26 @@ +# 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 new file mode 100644 index 0000000..36268bb --- /dev/null +++ b/docs/tr/changelog.md @@ -0,0 +1,76 @@ +# 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 new file mode 100644 index 0000000..8db782c --- /dev/null +++ b/docs/tr/clients.md @@ -0,0 +1,66 @@ +# İ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 new file mode 100644 index 0000000..af0c80f --- /dev/null +++ b/docs/tr/columnar.md @@ -0,0 +1,50 @@ +# 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 new file mode 100644 index 0000000..7f0ac09 --- /dev/null +++ b/docs/tr/configuration.md @@ -0,0 +1,106 @@ +# 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 new file mode 100644 index 0000000..8c33110 --- /dev/null +++ b/docs/tr/crossmodal.md @@ -0,0 +1,48 @@ +# Ç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 new file mode 100644 index 0000000..3d5bd36 --- /dev/null +++ b/docs/tr/deployment.md @@ -0,0 +1,68 @@ +# 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 new file mode 100644 index 0000000..b7ead1d --- /dev/null +++ b/docs/tr/distributed.md @@ -0,0 +1,73 @@ +# 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 new file mode 100644 index 0000000..483486b --- /dev/null +++ b/docs/tr/docker.md @@ -0,0 +1,78 @@ +# Docker Dağıtım Rehberi + +## Hızlı Başlangıç + +```bash +git clone https://github.com/katehonz/barabaDB.git +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 new file mode 100644 index 0000000..0213b10 --- /dev/null +++ b/docs/tr/fts.md @@ -0,0 +1,47 @@ +# 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 new file mode 100644 index 0000000..db2342c --- /dev/null +++ b/docs/tr/graph.md @@ -0,0 +1,42 @@ +# 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 new file mode 100644 index 0000000..759d198 --- /dev/null +++ b/docs/tr/index.md @@ -0,0 +1,59 @@ +# 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 new file mode 100644 index 0000000..a56fc0d --- /dev/null +++ b/docs/tr/installation.md @@ -0,0 +1,62 @@ +# 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 +curl https://nim-lang.org/choosenim/init.sh -sSf | sh +``` + +### macOS + +```bash +brew install nim +``` + +### Windows + +```powershell +winget install nim +``` + +## BaraDB Derleme + +```bash +git clone https://github.com/katehonz/barabaDB.git +cd barabaDB +nimble install -d -y +nim c -d:ssl -d:release --opt:speed -o:build/baradadb src/baradadb.nim +``` + +## İlk Çalıştırma + +```bash +./build/baradadb +curl http://localhost:9470/health +./build/baradadb --shell +``` + +## 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 new file mode 100644 index 0000000..d9e782b --- /dev/null +++ b/docs/tr/lsm.md @@ -0,0 +1,48 @@ +# 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/monitoring.md b/docs/tr/monitoring.md new file mode 100644 index 0000000..1598b10 --- /dev/null +++ b/docs/tr/monitoring.md @@ -0,0 +1,84 @@ +# İ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 new file mode 100644 index 0000000..46a3fbd --- /dev/null +++ b/docs/tr/performance.md @@ -0,0 +1,68 @@ +# 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 new file mode 100644 index 0000000..ffd928a --- /dev/null +++ b/docs/tr/protocol.md @@ -0,0 +1,67 @@ +# 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 new file mode 100644 index 0000000..ffbdc7d --- /dev/null +++ b/docs/tr/quickstart.md @@ -0,0 +1,99 @@ +# 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 new file mode 100644 index 0000000..118a507 --- /dev/null +++ b/docs/tr/schema.md @@ -0,0 +1,46 @@ +# Ş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 new file mode 100644 index 0000000..83d3205 --- /dev/null +++ b/docs/tr/security.md @@ -0,0 +1,76 @@ +# 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 new file mode 100644 index 0000000..916d53f --- /dev/null +++ b/docs/tr/storage.md @@ -0,0 +1,67 @@ +# 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 new file mode 100644 index 0000000..37eb176 --- /dev/null +++ b/docs/tr/transactions.md @@ -0,0 +1,47 @@ +# İş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 new file mode 100644 index 0000000..da48c29 --- /dev/null +++ b/docs/tr/troubleshooting.md @@ -0,0 +1,81 @@ +# 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 new file mode 100644 index 0000000..7442a1d --- /dev/null +++ b/docs/tr/udf.md @@ -0,0 +1,47 @@ +# 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 new file mode 100644 index 0000000..7f4b82c --- /dev/null +++ b/docs/tr/vector.md @@ -0,0 +1,65 @@ +# 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 new file mode 100644 index 0000000..5ca960b --- /dev/null +++ b/docs/zh/api-binary.md @@ -0,0 +1,62 @@ +# 二进制协议 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 new file mode 100644 index 0000000..2dbfa54 --- /dev/null +++ b/docs/zh/api-http.md @@ -0,0 +1,62 @@ +# 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 new file mode 100644 index 0000000..fb83299 --- /dev/null +++ b/docs/zh/api-websocket.md @@ -0,0 +1,67 @@ +# 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 new file mode 100644 index 0000000..1ccd8f1 --- /dev/null +++ b/docs/zh/architecture.md @@ -0,0 +1,197 @@ +# 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 new file mode 100644 index 0000000..bd439af --- /dev/null +++ b/docs/zh/backup.md @@ -0,0 +1,82 @@ +# 备份与恢复 + +## 在线快照 + +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 new file mode 100644 index 0000000..a38eaa9 --- /dev/null +++ b/docs/zh/baraql.md @@ -0,0 +1,492 @@ +# 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; +``` \ No newline at end of file diff --git a/docs/zh/btree.md b/docs/zh/btree.md new file mode 100644 index 0000000..02a73ae --- /dev/null +++ b/docs/zh/btree.md @@ -0,0 +1,26 @@ +# 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 new file mode 100644 index 0000000..6bc07c6 --- /dev/null +++ b/docs/zh/changelog.md @@ -0,0 +1,76 @@ +# 更新日志 + +## [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 new file mode 100644 index 0000000..e0dc36a --- /dev/null +++ b/docs/zh/clients.md @@ -0,0 +1,66 @@ +# 客户端 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 new file mode 100644 index 0000000..e66ec0e --- /dev/null +++ b/docs/zh/columnar.md @@ -0,0 +1,50 @@ +# 列式存储 + +用于分析查询和聚合的面向列的存储。 + +## 用法 + +```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 new file mode 100644 index 0000000..db2a145 --- /dev/null +++ b/docs/zh/configuration.md @@ -0,0 +1,217 @@ +# 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 v0.1.0 — 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 new file mode 100644 index 0000000..0344167 --- /dev/null +++ b/docs/zh/crossmodal.md @@ -0,0 +1,48 @@ +# 跨模态查询 + +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 new file mode 100644 index 0000000..be642fd --- /dev/null +++ b/docs/zh/deployment.md @@ -0,0 +1,249 @@ +# 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 new file mode 100644 index 0000000..7d6a84e --- /dev/null +++ b/docs/zh/distributed.md @@ -0,0 +1,91 @@ +# 分布式系统 + +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 new file mode 100644 index 0000000..c85ebeb --- /dev/null +++ b/docs/zh/docker.md @@ -0,0 +1,129 @@ +# Docker 部署指南 + +## 快速开始 + +```bash +git clone https://github.com/katehonz/barabaDB.git +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 new file mode 100644 index 0000000..c5f9a72 --- /dev/null +++ b/docs/zh/fts.md @@ -0,0 +1,47 @@ +# 全文搜索引擎 + +具有 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 new file mode 100644 index 0000000..7ba0b47 --- /dev/null +++ b/docs/zh/graph.md @@ -0,0 +1,42 @@ +# 图引擎 + +具有内置算法的邻接表存储，用于图遍历和分析。 + +## 用法 + +```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 new file mode 100644 index 0000000..d73b485 --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,59 @@ +# 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 new file mode 100644 index 0000000..aa1b7fb --- /dev/null +++ b/docs/zh/installation.md @@ -0,0 +1,309 @@ +# 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://github.com/katehonz/barabaDB.git +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 v0.1.0 — 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 v0.1.0 — 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 new file mode 100644 index 0000000..febd7a4 --- /dev/null +++ b/docs/zh/lsm.md @@ -0,0 +1,48 @@ +# 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/monitoring.md b/docs/zh/monitoring.md new file mode 100644 index 0000000..d09145f --- /dev/null +++ b/docs/zh/monitoring.md @@ -0,0 +1,104 @@ +# 监控与可观测性 + +## 健康检查 + +### 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 new file mode 100644 index 0000000..056d28d --- /dev/null +++ b/docs/zh/performance.md @@ -0,0 +1,94 @@ +# 性能指南 + +## 基准测试方法论 + +所有基准测试使用： +- **编译器**: 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 new file mode 100644 index 0000000..d97d03f --- /dev/null +++ b/docs/zh/protocol.md @@ -0,0 +1,67 @@ +# 协议参考 + +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 new file mode 100644 index 0000000..d87621e --- /dev/null +++ b/docs/zh/quickstart.md @@ -0,0 +1,134 @@ +# 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 new file mode 100644 index 0000000..0ef4d57 --- /dev/null +++ b/docs/zh/schema.md @@ -0,0 +1,46 @@ +# 模式系统 + +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 new file mode 100644 index 0000000..636b30a --- /dev/null +++ b/docs/zh/security.md @@ -0,0 +1,188 @@ +# 安全指南 + +## 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 new file mode 100644 index 0000000..04e3e53 --- /dev/null +++ b/docs/zh/storage.md @@ -0,0 +1,78 @@ +# 存储引擎 + +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 new file mode 100644 index 0000000..9fefcda --- /dev/null +++ b/docs/zh/transactions.md @@ -0,0 +1,77 @@ +# 事务与 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 new file mode 100644 index 0000000..388697b --- /dev/null +++ b/docs/zh/troubleshooting.md @@ -0,0 +1,118 @@ +# 故障排除指南 + +## 安装问题 + +### 未找到 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 new file mode 100644 index 0000000..30a55f7 --- /dev/null +++ b/docs/zh/udf.md @@ -0,0 +1,47 @@ +# 用户定义函数 + +使用自定义函数扩展 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 new file mode 100644 index 0000000..2c850db --- /dev/null +++ b/docs/zh/vector.md @@ -0,0 +1,65 @@ +# 向量搜索引擎 + +用于相似性搜索的本机 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