Update documentation and clients for v1.1.0

Documentation updates: - Fix v0.1.0 → v1.1.0 version numbers in en, ru, fa, zh docs - Add missing Window Functions, Multi-Tenant ERP, Supported Keywords sections to ru, fa, zh baraql.md (~105 lines each) - Expand Turkish and Arabic baraql.md (110 → 268 lines) - Expand Turkish and Arabic installation.md (62 → 307 lines) - Add new Bulgarian documentation files (18 new files) Client updates: - Python: Full async/await rewrite with asyncio, request queueing - Rust: Full async/await rewrite with tokio, async examples - Nim: Update README to v1.1.0 - All clients now support async patterns consistently
2026-05-14 23:05:47 +03:00
parent f7d4961125
commit c55d3080cf
48 changed files with 5792 additions and 544 deletions
@@ -97,5 +97,172 @@ RETURN friend.name;
 ```sql
 BEGIN;
 INSERT users { name := 'Alice', age := 30 };
+INSERT orders { user_id := last_insert_id(), total := 100 };
 COMMIT;
-```
+
+-- مع نقطة حفظ
+BEGIN;
+INSERT users { name := 'Bob', age := 25 };
+SAVEPOINT sp1;
+INSERT orders { user_id := last_insert_id(), total := 200 };
+-- خطأ، التراجع إلى نقطة الحفظ
+ROLLBACK TO sp1;
+COMMIT;
+```
+
+## البحث النصي الكامل
+
+```sql
+-- بحث أساسي
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('database programming');
+
+-- مع درجة الصلة
+SELECT title, relevance()
+FROM articles
+WHERE MATCH(title, body) AGAINST('Nim language')
+ORDER BY relevance() DESC;
+
+-- الوضع المنطقي
+SELECT * FROM articles
+WHERE MATCH(title, body) AGAINST('+Nim -Python' IN BOOLEAN MODE);
+
+-- البحث الضبابي
+SELECT * FROM articles
+WHERE MATCH(title) AGAINST('programing' WITH FUZZINESS 2);
+```
+
+## الدوال المحددة من المستخدم
+
+```sql
+-- تسجيل UDF
+CREATE FUNCTION greet(name str) -> str {
+  RETURN 'Hello, ' || name || '!';
+};
+
+-- استخدامها
+SELECT greet(name) FROM users;
+
+-- الدوال المدمجة
+SELECT abs(-5), sqrt(16), lower('HELLO'), len('test');
+```
+
+## تلميحات الاستعلام
+
+```sql
+-- فرض استخدام الفهرس
+SELECT /*+ USE_INDEX(idx_users_age) */ * FROM users WHERE age > 18;
+
+-- فرض البحث المتجهي التقريبي
+SELECT /*+ APPROXIMATE */ * FROM vectors
+ORDER BY cosine_distance(embedding, [...])
+LIMIT 10;
+
+-- التنفيذ المتوازي
+SELECT /*+ PARALLEL(4) */ * FROM large_table;
+```
+
+## دوال النوافذ
+
+```sql
+-- دوال الترتيب
+SELECT
+  name,
+  department,
+  ROW_NUMBER() OVER (PARTITION BY department ORDER BY salary DESC) AS rn,
+  RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS r,
+  DENSE_RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dr
+FROM employees;
+
+-- دوال القيمة
+SELECT
+  name,
+  salary,
+  LAG(salary, 1, 0) OVER (ORDER BY salary) AS prev_salary,
+  LEAD(salary, 1, 0) OVER (ORDER BY salary) AS next_salary,
+  FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS cheapest,
+  LAST_VALUE(name) OVER (PARTITION BY department ORDER BY salary) AS most_expensive
+FROM employees;
+
+-- دوال التوزيع
+SELECT name, NTILE(4) OVER (ORDER BY salary) AS quartile FROM employees;
+```
+
+### مواصفات الإطار
+
+```sql
+-- إطار ROWS
+SUM(salary) OVER (
+  PARTITION BY department
+  ORDER BY hire_date
+  ROWS BETWEEN 1 PRECEDING AND CURRENT ROW
+)
+
+-- إطار RANGE
+SUM(salary) OVER (
+  PARTITION BY department
+  ORDER BY hire_date
+  RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+)
+```
+
+## ERP متعدد المستأجرين
+
+يدعم BaraDB تشغيل عدة شركات (مستأجرين) في مثيل قاعدة بيانات واحد، باستخدام **أمان مستوى الصف (RLS)** مع **متغيرات الجلسة**.
+
+### متغيرات الجلسة
+
+```sql
+SET app.tenant_id = 'company-123';
+SELECT current_setting('app.tenant_id') AS tenant;
+```
+
+### المستخدم / الدور الحالي
+
+```sql
+SELECT current_user AS me, current_role AS my_role;
+```
+
+### عزل المستأجر عبر RLS
+
+```sql
+-- تمكين RLS على جدول
+ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
+
+-- إنشاء سياسة تصفية حسب المستأجر
+CREATE POLICY tenant_isolation ON invoices
+  FOR SELECT USING (tenant_id = current_setting('app.tenant_id'));
+
+-- كل جلسة ترى فقط بياناتها
+SET app.tenant_id = 'company-a';
+SELECT * FROM invoices;  -- صفوف company-a فقط
+```
+
+### لماذا متعدد المستأجرين؟
+
+- **مثيل واحد، مستأجرون كثيرون** — لا حاجة لتشغيل 100 قاعدة بيانات منفصلة
+- **مستندات JSONB** — تخزين مخطط مرن، سهل إضافة حقول لكل مستأجر
+- **RLS يضمن العزل** — قاعدة البيانات تفرض حدود المستأجر، وليس فقط التطبيق
+
+## الكلمات المفتاحية المدعومة
+
+| الفئة | الكلمات المفتاحية |
+|----------|----------|
+| DQL | SELECT, FROM, WHERE, ORDER BY, GROUP BY, HAVING, LIMIT, OFFSET, DISTINCT |
+| DML | INSERT, UPDATE, DELETE, SET, VALUES |
+| DDL | CREATE TYPE, DROP TYPE, CREATE INDEX, DROP INDEX, ALTER TYPE |
+| Join | INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, CROSS JOIN, ON |
+| Set | UNION, UNION ALL, INTERSECT, EXCEPT |
+| CTEs | WITH, RECURSIVE, AS |
+| Case | CASE, WHEN, THEN, ELSE, END |
+| Transaction | BEGIN, COMMIT, ROLLBACK, SAVEPOINT |
+| Graph | MATCH, RETURN, WHERE, shortestPath, type |
+| FTS | MATCH, AGAINST, relevance, IN BOOLEAN MODE, WITH FUZZINESS |
+| Vector | cosine_distance, euclidean_distance, inner_product, l1_distance, l2_distance, <-> |
+| JSON | ->, ->> |
+| FTS | @@ (تطابق BM25) |
+| Recovery | RECOVER TO TIMESTAMP |
+| Functions | count, sum, avg, min, max, stddev, variance, abs, sqrt, lower, upper, len, trim, substr, now, last_insert_id, current_setting |
+| Session | SET, current_setting, current_user, current_role |
+| Window | OVER, PARTITION BY, ROWS, RANGE, UNBOUNDED PRECEDING, CURRENT ROW, FOLLOWING |
+| Window Functions | ROW_NUMBER, RANK, DENSE_RANK, LEAD, LAG, FIRST_VALUE, LAST_VALUE, NTILE |
@@ -22,38 +22,284 @@
 ### لينكس

 ```bash
+# المثبت الرسمي
 curl https://nim-lang.org/choosenim/init.sh -sSf | sh
+
+# Ubuntu/Debian
+sudo apt-get update
+sudo apt-get install nim
+
+# Fedora
+sudo dnf install nim
+
+# Arch Linux
+sudo pacman -S nim
 ```

 ### macOS

 ```bash
+# Homebrew
 brew install nim
+
+# MacPorts
+sudo port install nim
 ```

 ### ويندوز

 ```powershell
+# باستخدام choosenim
+curl.exe -A "MSYS2_$(uname -m)" -L https://nim-lang.org/choosenim/init.ps1 | powershell -
+
+# باستخدام winget
 winget install nim
+
+# باستخدام scoop
+scoop install nim
 ```

+### التحقق من التثبيت
+
+```bash
+nim --version
+# المتوقع: Nim Compiler Version 2.2.0 أو أحدث
+```
+
+## تثبيت OpenSSL
+
+### لينكس
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install libssl-dev
+
+# Fedora
+sudo dnf install openssl-devel
+
+# Arch Linux
+sudo pacman -S openssl
+```
+
+### macOS
+
+OpenSSL مضمن مع النظام. إذا لزم الأمر:
+
+```bash
+brew install openssl
+```
+
+### ويندوز
+
+OpenSSL مضمن مع توزيع Nim ويندوز. للبناء اليدوي، قم بالتنزيل من [slproweb.com](https://slproweb.com/products/Win32OpenSSL.html).
+
 ## بناء BaraDB

+### استنساخ المستودع
+
 ```bash
 git clone https://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
+
+```bash
+# بناء التصحيح
+nimble build_debug
+
+# بناء الإصدار
+nimble build_release
+```
+
+#### تقليل حجم الملف الثنائي
+
+```bash
+nim c -d:ssl -d:release --opt:size -o:build/baradadb src/baradadb.nim
+strip build/baradadb
+```
+
+### التحقق من البناء
+
+```bash
+./build/baradadb --version
+# المتوقع: BaraDB v1.1.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
+# بناء إصدار RELEASE
+nimble build_release
+
+# التثبيت في /usr/local/bin
+sudo cp build/baradadb /usr/local/bin/
+sudo chmod +x /usr/local/bin/baradadb
+
+# إنشاء دليل البيانات
+sudo mkdir -p /var/lib/baradb
+sudo chmod 755 /var/lib/baradb
+```
+
+### الملف الثنائي المبنى مسبقًا
+
+قم بتنزيل أحدث إصدار لمنصتك:
+
+```bash
+# لينكس x86_64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-amd64
+chmod +x baradadb-linux-amd64
+mv baradadb-linux-amd64 /usr/local/bin/baradadb
+
+# لينكس ARM64
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-linux-arm64
+chmod +x baradadb-linux-arm64
+mv baradadb-linux-arm64 /usr/local/bin/baradadb
+
+# macOS
+wget https://github.com/katehonz/barabaDB/releases/latest/download/baradadb-darwin-amd64
+chmod +x baradadb-darwin-amd64
+mv baradadb-darwin-amd64 /usr/local/bin/baradadb
+```
+
+### Docker
+
+```bash
+# سحب الصورة الرسمية
+docker pull barabadb/barabadb:latest
+
+# التشغيل
+docker run -d \
+  -p 9472:9472 \
+  -p 9470:9470 \
+  -p 9471:9471 \
+  -v baradb_data:/data \
+  barabadb/barabadb
+```
+
+### Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+### الاستخدام المدمج (مشاريع Nim)
+
+أضف إلى ملف `.nimble` الخاص بك:
+
+```nim
+requires "barabadb >= 1.1.0"
+```
+
+استخدم في الكود:
+
+```nim
+import barabadb/storage/lsm
+
+var db = newLSMTree("./data")
+db.put("key", cast[seq[byte]]("value"))
+let (found, val) = db.get("key")
+db.close()
+```
+
 ## التشغيل الأول

 ```bash
+# بدء الخادم
 ./build/baradadb
+
+# المخرجات المتوقعة:
+# BaraDB v1.1.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)