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

docs: add multi-language documentation (ru, fa, zh, tr, ar)

Browse Source
This commit is contained in:
dimgigov
2026-05-07 23:42:55 +03:00
parent abb382c419
commit e9d3c7e9de
157 changed files with 14339 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5
View File
@@ -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
docs/ar/api-binary.md
+62
View File
@@ -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 | المورد غير موجود |
docs/ar/api-http.md
+62
View File
@@ -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"}'
```
docs/ar/api-websocket.md
+78
View File
@@ -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"}
}
```
docs/ar/architecture.md
+102
View File
@@ -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** | |
docs/ar/backup.md
+82
View File
@@ -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
docs/ar/baraql.md
+101
View File
@@ -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;
```
docs/ar/btree.md
+26
View File
@@ -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, >, <, >=, <=)
- المسح بالبادئة
- حجم الصفحة القابل للتكوين
- دعم المكرر
docs/ar/changelog.md
+76
View File
@@ -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% معدل النجاح
docs/ar/clients.md
+66
View File
@@ -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"}'
```
docs/ar/columnar.md
+50
View File
@@ -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` | منطقي |
docs/ar/configuration.md
+96
View File
@@ -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
```
docs/ar/crossmodal.md
+48
View File
@@ -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 |
docs/ar/deployment.md
+68
View File
@@ -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
```
docs/ar/distributed.md
+73
View File
@@ -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+ والتحقق منها.
docs/ar/docker.md
+78
View File
@@ -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` قوي
- [ ] تكوين قواعد جدار الحماية
- [ ] تكوين النسخ الاحتياطي المنتظم
- [ ] التحقق من حدود الموارد
- [ ] تكوين المراقبة
docs/ar/fts.md
+47
View File
@@ -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';
```
docs/ar/graph.md
+42
View File
@@ -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
""")
```
docs/ar/index.md
+59
View File
@@ -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)
---
*التوثيق العربي قيد الترجمة.*
docs/ar/installation.md
+62
View File
@@ -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)
docs/ar/lsm.md
+48
View File
@@ -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 بشكل متكرر
docs/ar/monitoring.md
+84
View File
@@ -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` | زيادة تجمع الاتصالات أو إضافة العقد |
docs/ar/performance.md
+68
View File
@@ -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
```
docs/ar/protocol.md
+67
View File
@@ -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`
docs/ar/quickstart.md
+99
View File
@@ -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)
docs/ar/schema.md
+46
View File
@@ -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` | بيانات ثنائية |
docs/ar/security.md
+76
View File
@@ -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
docs/ar/storage.md
+67
View File
@@ -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 "ربما موجود"
```
docs/ar/transactions.md
+47
View File
@@ -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
```
docs/ar/troubleshooting.md
+81
View File
@@ -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
```
docs/ar/udf.md
+47
View File
@@ -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;
```
docs/ar/vector.md
+65
View File
@@ -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)
```
docs/fa/api-binary.md
+62
View File
@@ -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 | منبع یافت نشد |
docs/fa/api-http.md
+62
View File
@@ -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"}'
```
docs/fa/api-websocket.md
+67
View File
@@ -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"
}
```
docs/fa/architecture.md
+197
View File
@@ -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 │
└─────────────┘
```
docs/fa/backup.md
+81
View File
@@ -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. کارهای پشتیبان‌گیری را مانیتور کنید
docs/fa/baraql.md
+492
View File
@@ -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<T>` | آرایه همگن | `[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;
```
docs/fa/btree.md
+25
View File
@@ -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
docs/fa/changelog.md
+70
View File
@@ -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 فاصله کسینوسی/ثانیه
docs/fa/clients.md
+66
View File
@@ -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"}'
```
docs/fa/columnar.md
+50
View File
@@ -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` | بولی |
docs/fa/configuration.md
+94
View File
@@ -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
```
docs/fa/crossmodal.md
+40
View File
@@ -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. موازی‌سازی شاخه‌های مستقل
docs/fa/deployment.md
+249
View File
@@ -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
```
docs/fa/distributed.md
+82
View File
@@ -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+ مشخص و تأیید شده‌اند.
docs/fa/docker.md
+113
View File
@@ -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
```
docs/fa/fts.md
+47
View File
@@ -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';
```
docs/fa/graph.md
+42
View File
@@ -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
""")
```
docs/fa/index.md
+59
View File
@@ -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)
---
*مستندات فارسی در دست تهیه است.*
docs/fa/installation.md
+309
View File
@@ -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)
docs/fa/lsm.md
+48
View File
@@ -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
docs/fa/monitoring.md
+78
View File
@@ -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` | افزایش استخر اتصال |
docs/fa/performance.md
+62
View File
@@ -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
```
docs/fa/protocol.md
+67
View File
@@ -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`
docs/fa/quickstart.md
+134
View File
@@ -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)
docs/fa/schema.md
+46
View File
@@ -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` | داده باینری |
docs/fa/security.md
+120
View File
@@ -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
docs/fa/storage.md
+78
View File
@@ -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)
```
docs/fa/transactions.md
+67
View File
@@ -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
```
docs/fa/troubleshooting.md
+87
View File
@@ -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
```
docs/fa/udf.md
+46
View File
@@ -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;
```
docs/fa/vector.md
+57
View File
@@ -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)
```
docs/index.md
+5
View File
@@ -6,6 +6,11 @@
- [English](en/)
- [Български (Bulgarian)](bg/)
- [Русский (Russian)](ru/)
- [فارسی (Farsi)](fa/)
- [中文 (Chinese)](zh/)
- [Türkçe (Turkish)](tr/)
- [العربية (Arabic)](ar/)
---
docs/ru/api-binary.md
+71
View File
@@ -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)
```
docs/ru/api-http.md
+83
View File
@@ -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 <token>" \
http://localhost:9470/api/users
```
docs/ru/api-websocket.md
+80
View File
@@ -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"}
}
```
docs/ru/architecture.md
+197
View File
@@ -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 │
└─────────────┘
```
docs/ru/backup.md
+120
View File
@@ -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**
docs/ru/baraql.md
+492
View File
@@ -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<T>` | Однородный массив | `[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;
```
docs/ru/btree.md
+34
View File
@@ -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, >, <, >=, <=)
- Префиксные сканирования
- Настраиваемый размер страницы
- Поддержка итераторов
## Сценарии использования
- Первичные ключевые индексы
- Вторичные индексы для часто запрашиваемых столбцов
- Данные с диапазонным разбиением
docs/ru/changelog.md
+78
View File
@@ -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% прохождение
docs/ru/clients.md
+82
View File
@@ -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` |
docs/ru/columnar.md
+58
View File
@@ -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 нагрузки
- Крупномасштабные агрегации
- Хранилища данных
- Анализ временных рядов
docs/ru/configuration.md
+217
View File
@@ -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 <file> Путь к конфигурационному файлу
-p, --port <port> TCP бинарный порт (по умолчанию: 9472)
--http-port <port> HTTP порт (по умолчанию: 9470)
--ws-port <port> WebSocket порт (по умолчанию: 9471)
-d, --data-dir <dir> Директория данных (по умолчанию: ./data)
--tls-cert <file> TLS сертификат
--tls-key <file> TLS закрытый ключ
--log-level <level> Уровень логирования: debug, info, warn, error
--log-file <file> Путь к файлу логов
--shell Запустить интерактивную оболочку
--version Показать версию
--recover Запустить восстановление WAL
--checkpoint <file> Чекпоинт для восстановления
-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
```
docs/ru/crossmodal.md
+63
View File
@@ -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 |
docs/ru/deployment.md
+44
View File
@@ -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
- [ ] Настроить мониторинг
docs/ru/distributed.md
+108
View File
@@ -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
```
docs/ru/docker.md
+189
View File
@@ -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
```
docs/ru/fts.md
+62
View File
@@ -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("Търсене в пълен текст")
```
docs/ru/graph.md
+51
View File
@@ -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
```
docs/ru/index.md
+59
View File
@@ -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)
---
*Документация на русском языке готовится к публикации.*
docs/ru/installation.md
+309
View File
@@ -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)
docs/ru/lsm.md
+61
View File
@@ -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
)
```
docs/ru/monitoring.md
+148
View File
@@ -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` | Проверить сеть, увеличить ресурсы |
docs/ru/performance.md
+95
View File
@@ -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
```
docs/ru/protocol.md
+87
View File
@@ -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'
}));
```
docs/ru/quickstart.md
+134
View File
@@ -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)
docs/ru/schema.md
+52
View File
@@ -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` | Двоичные данные |
docs/ru/security.md
+210
View File
@@ -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
docs/ru/storage.md
+78
View File
@@ -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)
```
docs/ru/transactions.md
+78
View File
@@ -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
```
docs/ru/troubleshooting.md
+168
View File
@@ -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 и логами
docs/ru/udf.md
+51
View File
@@ -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;
```
docs/ru/vector.md
+71
View File
@@ -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)
```
docs/tr/api-binary.md
+62
View File
@@ -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ı |
docs/tr/api-http.md
+62
View File
@@ -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"}'
```
docs/tr/api-websocket.md
+78
View File
@@ -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"}
}
```
docs/tr/architecture.md
+102
View File
@@ -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** | |
docs/tr/backup.md
+82
View File
@@ -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

Some files were not shown because too many files have changed in this diff Show More