docs: add multi-language documentation (ru, fa, zh, tr, ar)
This commit is contained in:
@@ -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 | منبع یافت نشد |
|
||||
@@ -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"}'
|
||||
```
|
||||
@@ -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"
|
||||
}
|
||||
```
|
||||
@@ -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 │
|
||||
└─────────────┘
|
||||
```
|
||||
@@ -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. کارهای پشتیبانگیری را مانیتور کنید
|
||||
@@ -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;
|
||||
```
|
||||
@@ -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
|
||||
@@ -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 فاصله کسینوسی/ثانیه
|
||||
@@ -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"}'
|
||||
```
|
||||
@@ -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` | بولی |
|
||||
@@ -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
|
||||
```
|
||||
@@ -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. موازیسازی شاخههای مستقل
|
||||
@@ -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
|
||||
```
|
||||
@@ -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+ مشخص و تأیید شدهاند.
|
||||
@@ -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
|
||||
```
|
||||
@@ -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';
|
||||
```
|
||||
@@ -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
|
||||
""")
|
||||
```
|
||||
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
*مستندات فارسی در دست تهیه است.*
|
||||
@@ -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)
|
||||
@@ -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
|
||||
@@ -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` | افزایش استخر اتصال |
|
||||
@@ -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
|
||||
```
|
||||
@@ -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`
|
||||
@@ -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)
|
||||
@@ -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` | داده باینری |
|
||||
@@ -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
|
||||
@@ -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)
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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
|
||||
```
|
||||
@@ -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;
|
||||
```
|
||||
@@ -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)
|
||||
```
|
||||
Reference in New Issue
Block a user