docs: update backup.md with multi-database and HTTP API docs

docs/bg/backup.md

@@ -1,36 +1,125 @@
 # Backup и Възстановяване
 
-BaraDB предоставя няколко стратегии за backup — от пълни snapshot-ове до инкрементални и online consistent backups.
+BaraDB предоставя няколко стратегии за backup — от пълни snapshot-ове до инкрементални, online consistent backups и multi-database архивиране.
-
-> ⚠️ **Настройка с множество бази данни**
-> BaraDB поддържа множество бази данни (`CREATE DATABASE`). Всяка база има собствена изолирана data директория (напр. `data/databases/<име>/`). Командите за backup, repair, checkpoint и migration работят върху **една директория наведнъж**. Ако използвате множество бази, пускайте командите за всяка база отделно или архивирайте цялата `data/databases/` директория.
 
 ## Архитектура
 
 ```
 ┌─────────────────────────────────────────┐
-│  Data Directory                         │
+│  Data Root                              │
-│  ├── MANIFEST          (atomic catalog) │
+│  └── databases/                         │
-│  ├── sstables/         (SSTable v3 CRC) │
+│      ├── default/                       │
-│  │   ├── 1.sst                          │
+│      │   ├── MANIFEST                   │
-│  │   └── 2.sst                          │
+│      │   ├── sstables/                  │
-│  └── wal/                               │
+│      │   └── wal/                       │
-│      ├── wal.log       (активен сегмент)│
+│      ├── mydb/                          │
-│      └── wal_archive/  (ротирани сегменти
+│      │   ├── MANIFEST                   │
+│      │   ├── sstables/                  │
+│      │   └── wal/                       │
+│      └── ...                            │
 └─────────────────────────────────────────┘
 ```
 
 ## Backup Инструмент
 
-Backup инструментът е в `src/barabadb/core/backup.nim`. Компилирайте го преди употреба:
-
 ```bash
 nim c -o:build/backup src/barabadb/core/backup.nim
 ```
 
-## SSTable Integrity (v3 CRC Footer)
+## Multi-Database Backup (Препоръчително)
 
-Всеки SSTable файл, записан от BaraDB, включва CRC32 footer:
+### Архивиране на всички бази
+
+```bash
+./build/backup backup --all-databases --data-root=./data/databases --output=all_$(date +%s).tar.gz
+```
+
+Архивът съдържа:
+- `backup.json` — метаданни (версия, timestamp, списък бази)
+- `databases/<име>/` — всяка база със своя MANIFEST, SSTables и WAL
+
+### Backup на единична база
+
+```bash
+./build/backup backup --database=default --data-root=./data/databases --output=default_$(date +%s).tar.gz
+```
+
+### Възстановяване на всички бази
+
+```bash
+./build/backup restore --input=all_1234567890.tar.gz --all-databases --data-root=./data/databases
+```
+
+### Възстановяване на единична база
+
+```bash
+./build/backup restore --input=default_1234567890.tar.gz --database=default --data-root=./data/databases
+```
+
+## Legacy Single-Directory Backup
+
+За обратна съвместимост със стари инсталации (една база в `data/server`):
+
+```bash
+./build/backup backup --data-dir=./data/server --output=legacy_$(date +%s).tar.gz
+./build/backup restore --input=legacy_1234567890.tar.gz --data-dir=./data/server
+```
+
+## Инкрементален Backup
+
+```bash
+./build/backup incremental --database=default --data-root=./data/databases --output=inc_$(date +%s).tar.gz
+```
+
+Включва само:
+- `MANIFEST`
+- Активни SSTables (от MANIFEST)
+- Текущ WAL (`wal/wal.log`)
+- WAL архив (`wal/wal_archive/*.log`)
+
+Всички SSTables се **проверяват с CRC** преди архивиране.
+
+## Online Consistent Backup
+
+```bash
+./build/backup backup --online --database=default --data-root=./data/databases --output=online_$(date +%s).tar.gz
+```
+
+Еквивалентно на:
+1. `checkpoint` (freeze memtable, flush, rotate WAL)
+2. `incremental backup`
+
+Безопасно за пускане докато сървърът работи.
+
+## HTTP API Backup
+
+Backup/restore е достъпен и през REST API (изисква admin JWT токен):
+
+```bash
+# Backup на всички бази
+curl -X POST http://localhost:9912/backup \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"all": true}'
+
+# Backup на единична база
+curl -X POST http://localhost:9912/backup \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"database": "default"}'
+
+# Списък с архиви
+curl http://localhost:9912/backups \
+  -H "Authorization: Bearer <token>"
+
+# Restore
+curl -X POST http://localhost:9912/restore \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "backup_1234567890.tar.gz", "all": true}'
+```
+
+## SSTable Integrity (v3 CRC Footer)
 
 ```
 [Header] 36 байта
@@ -43,36 +132,18 @@ nim c -o:build/backup src/barabadb/core/backup.nim
   dataCrc32, indexCrc32, bloomCrc32, reserved
 ```
 
-Това позволява независима проверка на всеки SSTable:
-
-```bash
-# Чрез Nim API
-import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
-```
-
 ## Storage Repair (`baradadb repair`)
 
-При съмнение за повреда, пуснете repair инструмента за конкретна база данни:
-
 ```bash
 # Dry run — само преглед
 ./build/baradadb repair --data-dir=./data/databases/default --dry-run
 
-# Пълен ремонт — проверка, преместване на битите файлове, WAL replay
+# Пълен ремонт
 ./build/baradadb repair --data-dir=./data/databases/default
 ```
 
-**Какво прави repair:**
-1. Сканира всички `sstables/*.sst` и проверява CRC
-2. Премества корумпираните SSTables в `<data-dir>/corrupt/`
-3. Пуска WAL replay за възстановяване на незаписани данни
-4. Докладва резултати
-
 ## MANIFEST Каталог
 
-Файлът `MANIFEST` е единственият източник на истина за активните SSTables. Обновява се атомично при всеки flush и compaction.
-
 ```json
 {
   "version": 1,
@@ -84,137 +155,55 @@ let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
 }
 ```
 
-Предимства:
-- **Консистентен изглед** — няма orphan SSTables след crash
-- **Бързо стартиране** — зарежда от MANIFEST вместо scan на директория
-- **Откриване на orphans** — `checkStorageConsistency()` докладва излишни/липсващи файлове
-
-При настройка с множество бази данни, всяка база поддържа собствен независим MANIFEST в своята data директория.
-
-## WAL Ротация
-
-Write-Ahead Log се ротира при достигане на 64MB:
-
-```
-wal/wal.log          → активен сегмент
-wal/wal_archive/
-  ├── wal.000001.log
-  ├── wal.000002.log
-  └── wal.000003.log
-```
-
-Ротацията се случва:
-- На всеки 1000 WAL записа (лека проверка на размер)
-- При всеки `flush` / `checkpoint`
-
 ## Checkpoint
 
-Checkpoint създава консистентна граница на storage без спиране на сървъра:
-
 ```bash
 ./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 
 **Как работи:**
-1. Freeze на memtable (swap към immutable, нов memtable за writes)
+1. Freeze на memtable (< 1ms)
-2. Flush на frozen memtable към SSTable
+2. Flush към SSTable
 3. Ротация на WAL
 4. Запис на MANIFEST
 
-Freeze-ът отнема **< 1ms**; flush-ът продължава паралелно с writes.
-
-## Backup Команди
-
-> Компилирайте backup инструмента първо: `nim c -o:build/backup src/barabadb/core/backup.nim`
-
-### Пълен Backup (tar.gz)
-
-```bash
-./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz
-```
-
-Архивира цялата data директория на посочената база данни.
-
-### Инкрементален Backup
-
-```bash
-./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
-```
-
-Включва само:
-- `MANIFEST`
-- Активни SSTables (от MANIFEST)
-- Текущ WAL (`wal/wal.log`)
-- WAL архив (`wal/wal_archive/*.log`)
-
-Всички SSTables се **проверяват с CRC** преди архивиране.
-
-### Online Consistent Backup
-
-```bash
-./build/backup backup --online --data-dir=./data/databases/default --output=backup_online_$(date +%s).tar.gz
-```
-
-Еквивалентно на:
-1. `checkpoint`
-2. `incremental backup`
-
-Безопасно за пускане докато сървърът работи. Checkpoint-ът създава консистентен snapshot, след което инкременталният backup го архивира.
-
 ## Миграция на SSTable Версии
 
-Ако имате legacy v1/v2 SSTables, мигрирайте ги към v3 за всяка база данни:
-
 ```bash
-# Преглед
 ./build/baradadb migrate --data-dir=./data/databases/default --dry-run
-
-# Миграция
 ./build/baradadb migrate --data-dir=./data/databases/default
 ```
 
-Миграцията пренаписва всеки legacy SSTable в текущия v3 формат (CRC footer) и обновява MANIFEST.
-
 ## Процедури за Възстановяване
 
-### Сценарий 1: Открит е Корумпиран SSTable
+### Сценарий 1: Корумпиран SSTable
 
 ```bash
-# Repair премества битите файлове и пуска WAL replay
 ./build/baradadb repair --data-dir=./data/databases/default
-
-# Проверка на консистентност
-./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
 
-### Сценарий 2: Възстановяване от Backup (Единична База)
+### Сценарий 2: Възстановяване от Multi-Database Backup
 
 ```bash
-# Спиране на сървъра
+# 1. Разархивиране
-# Разархивиране на backup в директорията на базата
+./build/backup restore --input=backup_latest.tar.gz --all-databases --data-root=./data/databases
-tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 
-# Рестарт — LSMTree зарежда от MANIFEST
+# 2. Repair за всяка база
-./build/baradadb
-```
-
-### Сценарий 3: Възстановяване на Всички Бази
-
-Ако сте архивирали цялото `data/databases/` дърво:
-
-```bash
-# 1. Разархивиране на последния backup
-tar -xzf backup_latest.tar.gz -C ./data
-
-# 2. Repair за всяка база за replay на наличния WAL
 for db in ./data/databases/*/; do
   ./build/baradadb repair --data-dir="$db" --dry-run
 done
 
-# 3. Стартиране на сървъра
+# 3. Стартиране
 ./build/baradadb
 ```
 
+### Сценарий 3: Ръчно разархивиране
+
+```bash
+tar -xzf backup_latest.tar.gz -C ./data
+# Архивът съдържа: databases/<име>/ + backup.json
+```
+
 ## Изисквания за Съхранение
 
 | Тип Backup | Размер | Честота | Задържане |
@@ -225,9 +214,9 @@ done
 
 ## Най-добри Практики
 
-1. **Пускайте repair след некоректно спиране** — `./build/baradadb repair`
+1. **Използвайте `--all-databases`** за пълен backup в multi-DB сетъп
-2. **Мигрирайте legacy SSTables** — `./build/baradadb migrate`
+2. **Тествайте възстановяването редовно** — Backup, който не може да бъде възстановен, е безполезен
-3. **Тествайте възстановяването редовно** — Backup, който не може да бъде възстановен, е безполезен
+3. **Пускайте repair след некоректно спиране**
-4. **Използвайте incremental + checkpoint** — За чести консистентни snapshot-ове
+4. **Съхранявайте backups извън локацията** — S3, GCS или друг сървър
-5. **Съхранявайте backups извън локацията** — S3, GCS или друг сървър
+5. **Използвайте incremental + checkpoint** — За чести консистентни snapshot-ове
-6. **Следете MANIFEST sequence** — Трябва да расте монотонно с flush-овете
+6. **Мониторирайте `/backups` endpoint** — През админ панела или API

docs/en/backup.md

@@ -1,36 +1,125 @@
 # Backup & Recovery
 
-BaraDB provides multiple backup strategies ranging from full snapshots to incremental and online consistent backups.
+BaraDB provides multiple backup strategies ranging from full snapshots to incremental, online consistent backups, and multi-database archiving.
-
-> ⚠️ **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
 
 ```
 ┌─────────────────────────────────────────┐
-│  Data Directory                         │
+│  Data Root                              │
-│  ├── MANIFEST          (atomic catalog) │
+│  └── databases/                         │
-│  ├── sstables/         (SSTable v3 CRC) │
+│      ├── default/                       │
-│  │   ├── 1.sst                          │
+│      │   ├── MANIFEST                   │
-│  │   └── 2.sst                          │
+│      │   ├── sstables/                  │
-│  └── wal/                               │
+│      │   └── wal/                       │
-│      ├── wal.log       (active segment) │
+│      ├── mydb/                          │
-│      └── wal_archive/  (rotated segments│
+│      │   ├── MANIFEST                   │
+│      │   ├── sstables/                  │
+│      │   └── wal/                       │
+│      └── ...                            │
 └─────────────────────────────────────────┘
 ```
 
 ## 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)
+## Multi-Database Backup (Recommended)
 
-Every SSTable file written by BaraDB includes a CRC32 footer:
+### Backup all databases
+
+```bash
+./build/backup backup --all-databases --data-root=./data/databases --output=all_$(date +%s).tar.gz
+```
+
+The archive contains:
+- `backup.json` — metadata (version, timestamp, database list)
+- `databases/<name>/` — each database with its MANIFEST, SSTables, and WAL
+
+### Backup a single database
+
+```bash
+./build/backup backup --database=default --data-root=./data/databases --output=default_$(date +%s).tar.gz
+```
+
+### Restore all databases
+
+```bash
+./build/backup restore --input=all_1234567890.tar.gz --all-databases --data-root=./data/databases
+```
+
+### Restore a single database
+
+```bash
+./build/backup restore --input=default_1234567890.tar.gz --database=default --data-root=./data/databases
+```
+
+## Legacy Single-Directory Backup
+
+For backward compatibility with older installations (single database in `data/server`):
+
+```bash
+./build/backup backup --data-dir=./data/server --output=legacy_$(date +%s).tar.gz
+./build/backup restore --input=legacy_1234567890.tar.gz --data-dir=./data/server
+```
+
+## Incremental Backup
+
+```bash
+./build/backup incremental --database=default --data-root=./data/databases --output=inc_$(date +%s).tar.gz
+```
+
+Includes only:
+- `MANIFEST`
+- Active SSTables (from MANIFEST)
+- Current WAL (`wal/wal.log`)
+- WAL archive (`wal/wal_archive/*.log`)
+
+All SSTables are **CRC-verified** before archiving.
+
+## Online Consistent Backup
+
+```bash
+./build/backup backup --online --database=default --data-root=./data/databases --output=online_$(date +%s).tar.gz
+```
+
+Equivalent to:
+1. `checkpoint` (freeze memtable, flush, rotate WAL)
+2. `incremental backup`
+
+Safe to run while the server is running.
+
+## HTTP API Backup
+
+Backup/restore is also available via REST API (requires admin JWT token):
+
+```bash
+# Backup all databases
+curl -X POST http://localhost:9912/backup \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"all": true}'
+
+# Backup single database
+curl -X POST http://localhost:9912/backup \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"database": "default"}'
+
+# List backups
+curl http://localhost:9912/backups \
+  -H "Authorization: Bearer <token>"
+
+# Restore
+curl -X POST http://localhost:9912/restore \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"input": "backup_1234567890.tar.gz", "all": true}'
+```
+
+## SSTable Integrity (v3 CRC Footer)
 
 ```
 [Header] 36 bytes
@@ -43,36 +132,18 @@ Every SSTable file written by BaraDB includes a CRC32 footer:
   dataCrc32, indexCrc32, bloomCrc32, reserved
 ```
 
-This enables independent verification of each SSTable:
-
-```bash
-# Via Nim API
-import barabadb/storage/lsm
-let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")
-```
-
 ## Storage Repair (`baradadb repair`)
 
-If corruption is suspected, run the repair tool against a specific database directory:
-
 ```bash
 # Dry run — preview only
 ./build/baradadb repair --data-dir=./data/databases/default --dry-run
 
-# Full repair — verify, move corrupt files, replay WAL
+# Full repair
 ./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-dir>/corrupt/`
-3. Replays WAL to recover unflushed committed data
-4. Reports results
-
 ## MANIFEST Catalog
 
-The `MANIFEST` file is the single source of truth for active SSTables. It is updated atomically on every flush and compaction.
-
 ```json
 {
   "version": 1,
@@ -84,129 +155,40 @@ The `MANIFEST` file is the single source of truth for active SSTables. It is upd
 }
 ```
 
-Benefits:
-- **Consistent view** — no orphan SSTables after crash
-- **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:
-
-```
-wal/wal.log          → active segment
-wal/wal_archive/
-  ├── wal.000001.log
-  ├── wal.000002.log
-  └── wal.000003.log
-```
-
-Rotation happens:
-- Every 1000 WAL entries (lightweight size check)
-- On every `flush` / `checkpoint`
-
 ## Checkpoint
 
-A checkpoint creates a consistent storage boundary without stopping the server:
-
 ```bash
 ./build/baradadb checkpoint --data-dir=./data/databases/default
 ```
 
 **How it works:**
-1. Freeze memtable (swap to immutable, new memtable for writes)
+1. Freeze memtable (< 1ms)
-2. Flush frozen memtable to SSTable
+2. Flush to SSTable
 3. Rotate WAL
 4. Write MANIFEST
 
-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/databases/default --output=backup_$(date +%s).tar.gz
-```
-
-Archives the entire data directory of the specified database.
-
-### Incremental Backup
-
-```bash
-./build/backup incremental --data-dir=./data/databases/default --output=backup_inc_$(date +%s).tar.gz
-```
-
-Includes only:
-- `MANIFEST`
-- Active SSTables (from MANIFEST)
-- Current WAL (`wal/wal.log`)
-- WAL archive (`wal/wal_archive/*.log`)
-
-All SSTables are **CRC-verified** before archiving.
-
-### Online Consistent Backup
-
-```bash
-./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 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 per database:
-
 ```bash
-# Preview
 ./build/baradadb migrate --data-dir=./data/databases/default --dry-run
-
-# Migrate
 ./build/baradadb migrate --data-dir=./data/databases/default
 ```
 
-Migration rewrites each legacy SSTable with the current v3 format (CRC footer) and updates the MANIFEST.
-
 ## Recovery Procedures
 
-### Scenario 1: Corrupt SSTable Detected
+### Scenario 1: Corrupt SSTable
 
 ```bash
-# Repair moves corrupt files and replays WAL
 ./build/baradadb repair --data-dir=./data/databases/default
-
-# Verify consistency
-./build/baradadb repair --data-dir=./data/databases/default --dry-run
 ```
 
-### Scenario 2: Restore from Backup (Single Database)
+### Scenario 2: Restore from Multi-Database Backup
 
 ```bash
-# Stop the server
+# 1. Extract
-# Extract backup into the database directory
+./build/backup restore --input=backup_latest.tar.gz --all-databases --data-root=./data/databases
-tar -xzf backup_1234567890.tar.gz -C ./data/databases/default
 
-# Restart — LSMTree loads from MANIFEST
+# 2. Repair each database
-./build/baradadb
-```
-
-### 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 for each database to replay any available WAL
 for db in ./data/databases/*/; do
   ./build/baradadb repair --data-dir="$db" --dry-run
 done
@@ -215,6 +197,13 @@ done
 ./build/baradadb
 ```
 
+### Scenario 3: Manual extraction
+
+```bash
+tar -xzf backup_latest.tar.gz -C ./data
+# Archive contains: databases/<name>/ + backup.json
+```
+
 ## Storage Requirements
 
 | Backup Type | Size | Frequency | Retention |
@@ -225,9 +214,9 @@ done
 
 ## Best Practices
 
-1. **Run repair after unclean shutdown** — `./build/baradadb repair`
+1. **Use `--all-databases`** for full backups in multi-DB setups
-2. **Migrate legacy SSTables** — `./build/baradadb migrate`
+2. **Test restores regularly** — A backup you can't restore is useless
-3. **Test restores regularly** — A backup you can't restore is useless
+3. **Run repair after unclean shutdown**
-4. **Use incremental + checkpoint** — For frequent consistent snapshots
+4. **Store backups offsite** — S3, GCS, or another server
-5. **Store backups offsite** — S3, GCS, or another server
+5. **Use incremental + checkpoint** — For frequent consistent snapshots
-6. **Monitor MANIFEST sequence** — Should grow monotonically with flushes
+6. **Monitor `/backups` endpoint** — Via admin panel or API