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
This commit is contained in:
+42
-23
@@ -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
|
||||
tar -xzf backup_1234567890.tar.gz -C ./data
|
||||
# Разархивиране на backup в директорията на базата
|
||||
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
|
||||
./build/baradadb repair --data-dir=./data
|
||||
# 2. Repair за всяка база за replay на наличния WAL
|
||||
for db in ./data/databases/*/; do
|
||||
./build/baradadb repair --data-dir="$db" --dry-run
|
||||
done
|
||||
|
||||
# 3. Стартиране на сървъра
|
||||
./build/baradadb
|
||||
|
||||
@@ -2,6 +2,9 @@
|
||||
|
||||
BaraDB поддържа разпределено внедряване с Raft консенсус, шардиране, репликация и gossip протокол.
|
||||
|
||||
> ⚠️ **Ограничение при множество бази данни**
|
||||
> Разпределените модули (Raft, шардиране и репликация) в момента работят само с **`default`** базата данни. Ако използвате множество бази (`CREATE DATABASE`, `USE DATABASE`), разпределените функции още не ги обхващат. Всяка база данни се нуждае от отделна кластър конфигурация.
|
||||
|
||||
## Raft Консенсус
|
||||
|
||||
Leader election и log репликация:
|
||||
|
||||
@@ -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 <име>` преди миграционните команди.
|
||||
|
||||
## Типове Полета
|
||||
|
||||
| Тип | Описание |
|
||||
|
||||
+4
-1
@@ -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()
|
||||
|
||||
+42
-23
@@ -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
|
||||
tar -xzf backup_1234567890.tar.gz -C ./data
|
||||
# Extract backup into the database directory
|
||||
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
|
||||
./build/baradadb repair --data-dir=./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
|
||||
|
||||
# 3. Start server
|
||||
./build/baradadb
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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 |
|
||||
|
||||
+4
-1
@@ -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()
|
||||
|
||||
Reference in New Issue
Block a user