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
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)
```