docs: update distributed/backup/schema/storage for multi-database

- Add multi-database limitations to distributed docs
- Fix backup commands and add multi-database backup guidance
- Add SQL migration section to schema docs
- Update storage examples to use per-database paths

docs/bg/backup.md

@@ -2,6 +2,9 @@
 
 BaraDB предоставя няколко стратегии за backup — от пълни snapshot-ове до инкрементални и online consistent backups.
 
+> ⚠️ **Настройка с множество бази данни**
+> BaraDB поддържа множество бази данни (`CREATE DATABASE`). Всяка база има собствена изолирана data директория (напр. `data/databases/<име>/`). Командите за backup, repair, checkpoint и migration работят върху **една директория наведнъж**. Ако използвате множество бази, пускайте командите за всяка база отделно или архивирайте цялата `data/databases/` директория.
+
 ## Архитектура
 
 ```
@@ -17,6 +20,14 @@ BaraDB предоставя няколко стратегии за backup — о
 └─────────────────────────────────────────┘
 ```
 
+## Backup Инструмент
+
+Backup инструментът е в `src/barabadb/core/backup.nim`. Компилирайте го преди употреба:
+
+```bash
+nim c -o:build/backup src/barabadb/core/backup.nim
+```
+
 ## SSTable Integrity (v3 CRC Footer)
 
 Всеки SSTable файл, записан от BaraDB, включва CRC32 footer:
@@ -37,24 +48,24 @@ BaraDB предоставя няколко стратегии за backup — о
 ```bash
 # Чрез Nim API
 import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/sstables/1.sst")
+let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
 ```
 
-## Storage Repair (`baradb repair`)
+## Storage Repair (`baradadb repair`)
 
-При съмнение за повреда, пуснете repair инструмента:
+При съмнение за повреда, пуснете repair инструмента за конкретна база данни:
 
 ```bash
 # Dry run — само преглед
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 
 # Пълен ремонт — проверка, преместване на битите файлове, WAL replay
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 ```
 
 **Какво прави repair:**
 1. Сканира всички `sstables/*.sst` и проверява CRC
-2. Премества корумпираните SSTables в `data/corrupt/`
+2. Премества корумпираните SSTables в `<data-dir>/corrupt/`
 3. Пуска WAL replay за възстановяване на незаписани данни
 4. Докладва резултати
 
@@ -78,6 +89,8 @@ let (ok, msg) = verifySSTable("data/sstables/1.sst")
 - **Бързо стартиране** — зарежда от MANIFEST вместо scan на директория
 - **Откриване на orphans** — `checkStorageConsistency()` докладва излишни/липсващи файлове
 
+При настройка с множество бази данни, всяка база поддържа собствен независим MANIFEST в своята data директория.
+
 ## WAL Ротация
 
 Write-Ahead Log се ротира при достигане на 64MB:
@@ -99,7 +112,7 @@ wal/wal_archive/
 Checkpoint създава консистентна граница на storage без спиране на сървъра:
 
 ```bash
-./build/baradadb checkpoint --data-dir=./data
+./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 
 **Как работи:**
@@ -112,18 +125,20 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 
 ## Backup Команди
 
+> Компилирайте backup инструмента първо: `nim c -o:build/backup src/barabadb/core/backup.nim`
+
 ### Пълен Backup (tar.gz)
 
 ```bash
-./build/backup backup --data-dir=./data --output=backup_$(date +%s).tar.gz
+./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz
 ```
 
-Архивира цялата data директория.
+Архивира цялата data директория на посочената база данни.
 
 ### Инкрементален Backup
 
 ```bash
-./build/backup incremental --data-dir=./data --output=backup_inc_$(date +%s).tar.gz
+./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
 ```
 
 Включва само:
@@ -137,25 +152,25 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 ### Online Consistent Backup
 
 ```bash
-./build/baradadb backup --online --output=backup_online_$(date +%s).tar.gz
+./build/backup backup --online --data-dir=./data/databases/default --output=backup_online_$(date +%s).tar.gz
 ```
 
 Еквивалентно на:
 1. `checkpoint`
 2. `incremental backup`
 
-**Безопасно за пускане, когато сървърът е спрян.** Ако сървърът работи, използвайте `backup incremental`.
+Безопасно за пускане докато сървърът работи. Checkpoint-ът създава консистентен snapshot, след което инкременталният backup го архивира.
 
 ## Миграция на SSTable Версии
 
-Ако имате legacy v1/v2 SSTables, мигрирайте ги към v3:
+Ако имате legacy v1/v2 SSTables, мигрирайте ги към v3 за всяка база данни:
 
 ```bash
 # Преглед
-./build/baradadb migrate --data-dir=./data --dry-run
+./build/baradadb migrate --data-dir=./data/databases/default --dry-run
 
 # Миграция
-./build/baradadb migrate --data-dir=./data
+./build/baradadb migrate --data-dir=./data/databases/default
 ```
 
 Миграцията пренаписва всеки legacy SSTable в текущия v3 формат (CRC footer) и обновява MANIFEST.
@@ -166,31 +181,35 @@ Freeze-ът отнема **< 1ms**; flush-ът продължава парале
 
 ```bash
 # Repair премества битите файлове и пуска WAL replay
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 
 # Проверка на консистентност
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
 
-### Сценарий 2: Възстановяване от Backup
+### Сценарий 2: Възстановяване от Backup (Единична База)
 
 ```bash
 # Спиране на сървъра
-# Разархивиране на backup
+# Разархивиране на backup в директорията на базата
-tar -xzf backup_1234567890.tar.gz -C ./data
+tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 
 # Рестарт — LSMTree зарежда от MANIFEST
 ./build/baradadb
 ```
 
-### Сценарий 3: Пълна Загуба на Данни
+### Сценарий 3: Възстановяване на Всички Бази
+
+Ако сте архивирали цялото `data/databases/` дърво:
 
 ```bash
 # 1. Разархивиране на последния backup
 tar -xzf backup_latest.tar.gz -C ./data
 
-# 2. Repair за replay на наличния WAL
+# 2. Repair за всяка база за replay на наличния WAL
-./build/baradadb repair --data-dir=./data
+for db in ./data/databases/*/; do
+  ./build/baradadb repair --data-dir="$db" --dry-run
+done
 
 # 3. Стартиране на сървъра
 ./build/baradadb

docs/bg/distributed.md

@@ -2,6 +2,9 @@
 
 BaraDB поддържа разпределено внедряване с Raft консенсус, шардиране, репликация и gossip протокол.
 
+> ⚠️ **Ограничение при множество бази данни**
+> Разпределените модули (Raft, шардиране и репликация) в момента работят само с **`default`** базата данни. Ако използвате множество бази (`CREATE DATABASE`, `USE DATABASE`), разпределените функции още не ги обхващат. Всяка база данни се нуждае от отделна кластър конфигурация.
+
 ## Raft Консенсус
 
 Leader election и log репликация:

docs/bg/schema.md

@@ -26,6 +26,32 @@ s.addType("default", employee)
 let resolved = s.resolveInheritance(employee)
 ```
 
+## SQL Миграции
+
+BaraDB поддържа SQL миграции, изпълнявани чрез BaraQL:
+
+```sql
+-- Създаване на миграционна таблица
+CREATE MIGRATION TABLE my_migration;
+
+-- Прилагане на чакащи миграции
+MIGRATION UP;
+
+-- Rollback на последната миграция
+MIGRATION DOWN;
+
+-- Прилагане на всички чакащи миграции наведнъж
+MIGRATION UP BATCH;
+
+-- Dry-run за преглед на промените
+MIGRATION DRYRUN;
+
+-- Проверка на статуса
+MIGRATION STATUS;
+```
+
+Миграционните скриптове се съхраняват вътре в LSMTree на всяка база данни и са изолирани per database. При използване на множество бази, изпълнете `USE DATABASE <име>` преди миграционните команди.
+
 ## Типове Полета
 
 | Тип | Описание |

docs/bg/storage.md

@@ -6,12 +6,15 @@ BaraDB предоставя множество storage двигатели, оп
 
 Основният storage engine с write-оптимизирана append-only лог структура.
 
+> **Бележка за множество бази данни**
+> Всяка база данни има собствена изолирана директория (напр. `data/databases/<име>/`). Примерите по-долу използват `./data` като placeholder — заменете с реалния път до вашата база.
+
 ### Употреба
 
 ```nim
 import barabadb/storage/lsm
 
-var db = newLSMTree("./data")
+var db = newLSMTree("./data/databases/default")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()

docs/en/backup.md

@@ -2,6 +2,9 @@
 
 BaraDB provides multiple backup strategies ranging from full snapshots to incremental and online consistent backups.
 
+> ⚠️ **Multi-Database Setup**
+> BaraDB supports multiple databases (`CREATE DATABASE`). Each database has its own isolated data directory (e.g. `data/databases/<name>/`). Backup, repair, checkpoint, and migration commands operate on **one directory at a time**. If you use multiple databases, run the commands for each database separately or back up the entire `data/databases/` parent directory.
+
 ## Architecture
 
 ```
@@ -17,6 +20,14 @@ BaraDB provides multiple backup strategies ranging from full snapshots to increm
 └─────────────────────────────────────────┘
 ```
 
+## Backup Tool
+
+The backup tool is shipped as `src/barabadb/core/backup.nim`. Build it before use:
+
+```bash
+nim c -o:build/backup src/barabadb/core/backup.nim
+```
+
 ## SSTable Integrity (v3 CRC Footer)
 
 Every SSTable file written by BaraDB includes a CRC32 footer:
@@ -37,24 +48,24 @@ This enables independent verification of each SSTable:
 ```bash
 # Via Nim API
 import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/sstables/1.sst")
+let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
 ```
 
-## Storage Repair (`baradb repair`)
+## Storage Repair (`baradadb repair`)
 
-If corruption is suspected, run the repair tool:
+If corruption is suspected, run the repair tool against a specific database directory:
 
 ```bash
 # Dry run — preview only
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 
 # Full repair — verify, move corrupt files, replay WAL
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 ```
 
 **What repair does:**
 1. Scans all `sstables/*.sst` and verifies CRC
-2. Moves corrupt SSTables to `data/corrupt/`
+2. Moves corrupt SSTables to `<data-dir>/corrupt/`
 3. Replays WAL to recover unflushed committed data
 4. Reports results
 
@@ -78,6 +89,8 @@ Benefits:
 - **Fast startup** — load from MANIFEST instead of directory scan
 - **Orphan detection** — `checkStorageConsistency()` reports extra/missing files
 
+In a multi-database setup, each database maintains its own independent MANIFEST inside its data directory.
+
 ## WAL Rotation
 
 The Write-Ahead Log rotates when it reaches 64MB:
@@ -99,7 +112,7 @@ Rotation happens:
 A checkpoint creates a consistent storage boundary without stopping the server:
 
 ```bash
-./build/baradadb checkpoint --data-dir=./data
+./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 
 **How it works:**
@@ -112,18 +125,20 @@ The freeze takes **< 1ms**; the flush proceeds concurrently with writes.
 
 ## Backup Commands
 
+> Build the backup tool first: `nim c -o:build/backup src/barabadb/core/backup.nim`
+
 ### Full Backup (tar.gz)
 
 ```bash
-./build/backup backup --data-dir=./data --output=backup_$(date +%s).tar.gz
+./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz
 ```
 
-Archives the entire data directory.
+Archives the entire data directory of the specified database.
 
 ### Incremental Backup
 
 ```bash
-./build/backup incremental --data-dir=./data --output=backup_inc_$(date +%s).tar.gz
+./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
 ```
 
 Includes only:
@@ -137,25 +152,25 @@ All SSTables are **CRC-verified** before archiving.
 ### Online Consistent Backup
 
 ```bash
-./build/baradadb backup --online --output=backup_online_$(date +%s).tar.gz
+./build/backup backup --online --data-dir=./data/databases/default --output=backup_online_$(date +%s).tar.gz
 ```
 
 Equivalent to:
 1. `checkpoint`
 2. `incremental backup`
 
-**Safe to run while the server is stopped.** If the server is running, use `backup incremental` instead.
+Safe to run while the server is running. The checkpoint creates a consistent snapshot, then the incremental backup archives it.
 
 ## SSTable Version Migration
 
-If you have legacy v1/v2 SSTables, migrate them to v3:
+If you have legacy v1/v2 SSTables, migrate them to v3 per database:
 
 ```bash
 # Preview
-./build/baradadb migrate --data-dir=./data --dry-run
+./build/baradadb migrate --data-dir=./data/databases/default --dry-run
 
 # Migrate
-./build/baradadb migrate --data-dir=./data
+./build/baradadb migrate --data-dir=./data/databases/default
 ```
 
 Migration rewrites each legacy SSTable with the current v3 format (CRC footer) and updates the MANIFEST.
@@ -166,31 +181,35 @@ Migration rewrites each legacy SSTable with the current v3 format (CRC footer) a
 
 ```bash
 # Repair moves corrupt files and replays WAL
-./build/baradadb repair --data-dir=./data
+./build/baradadb repair --data-dir=./data/databases/default
 
 # Verify consistency
-./build/baradadb repair --data-dir=./data --dry-run
+./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
 
-### Scenario 2: Restore from Backup
+### Scenario 2: Restore from Backup (Single Database)
 
 ```bash
 # Stop the server
-# Extract backup
+# Extract backup into the database directory
-tar -xzf backup_1234567890.tar.gz -C ./data
+tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 
 # Restart — LSMTree loads from MANIFEST
 ./build/baradadb
 ```
 
-### Scenario 3: Complete Data Loss
+### Scenario 3: Restore All Databases
+
+If you back up the entire `data/databases/` tree:
 
 ```bash
 # 1. Extract latest backup
 tar -xzf backup_latest.tar.gz -C ./data
 
-# 2. Run repair to replay any available WAL
+# 2. Run repair for each database to replay any available WAL
-./build/baradadb repair --data-dir=./data
+for db in ./data/databases/*/; do
+  ./build/baradadb repair --data-dir="$db" --dry-run
+done
 
 # 3. Start server
 ./build/baradadb

docs/en/distributed.md

@@ -2,6 +2,9 @@
 
 BaraDB supports distributed deployment with Raft consensus, sharding, and replication.
 
+> ⚠️ **Multi-Database Limitation**
+> The distributed modules (Raft, sharding, and replication) are currently wired to the **`default`** database only. If you use multiple databases (`CREATE DATABASE`, `USE DATABASE`), distributed features do not yet span across them. Each database would need its own cluster setup.
+
 ## Raft Consensus
 
 Leader election and log replication:

docs/en/schema.md

@@ -41,6 +41,32 @@ let diff = s.diff(oldSchema, newSchema)
 
 Schema changes are tracked and can generate migration scripts.
 
+## SQL Migrations
+
+BaraDB supports SQL-level migrations executed through BaraQL:
+
+```sql
+-- Create a migration table
+CREATE MIGRATION TABLE my_migration;
+
+-- Apply pending migrations
+MIGRATION UP;
+
+-- Rollback last migration
+MIGRATION DOWN;
+
+-- Apply all pending migrations in batch
+MIGRATION UP BATCH;
+
+-- Dry-run to preview changes
+MIGRATION DRYRUN;
+
+-- Check migration status
+MIGRATION STATUS;
+```
+
+Migration scripts are stored inside each database's LSMTree and are isolated per database. When using multiple databases, run `USE DATABASE <name>` before executing migration commands.
+
 ## Property Types
 
 | Type | Description |

docs/en/storage.md

@@ -6,12 +6,15 @@ BaraDB provides multiple storage engines optimized for different access patterns
 
 The primary storage engine with write-optimized append-only log structure.
 
+> **Multi-Database Note**
+> Each database gets its own isolated data directory (e.g. `data/databases/<name>/`). The examples below use `./data` as a placeholder — substitute with your actual database path.
+
 ### Usage
 
 ```nim
 import barabadb/storage/lsm
 
-var db = newLSMTree("./data")
+var db = newLSMTree("./data/databases/default")
 db.put("key1", cast[seq[byte]]("value1"))
 let (found, value) = db.get("key1")
 db.close()