From 4a83eb678306b91616b2f29498d4bd83abf11c55 Mon Sep 17 00:00:00 2001 From: dimgigov Date: Thu, 21 May 2026 09:44:25 +0300 Subject: [PATCH] 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 | 65 +++++++++++++++++++++++++++--------------- docs/bg/distributed.md | 3 ++ docs/bg/schema.md | 26 +++++++++++++++++ docs/bg/storage.md | 5 +++- docs/en/backup.md | 65 +++++++++++++++++++++++++++--------------- docs/en/distributed.md | 3 ++ docs/en/schema.md | 26 +++++++++++++++++ docs/en/storage.md | 5 +++- 8 files changed, 150 insertions(+), 48 deletions(-) diff --git a/docs/bg/backup.md b/docs/bg/backup.md index 5c761c6..ad8e477 100644 --- a/docs/bg/backup.md +++ b/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 в `/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 diff --git a/docs/bg/distributed.md b/docs/bg/distributed.md index 927e2dc..b412ba7 100644 --- a/docs/bg/distributed.md +++ b/docs/bg/distributed.md @@ -2,6 +2,9 @@ BaraDB поддържа разпределено внедряване с Raft консенсус, шардиране, репликация и gossip протокол. +> ⚠️ **Ограничение при множество бази данни** +> Разпределените модули (Raft, шардиране и репликация) в момента работят само с **`default`** базата данни. Ако използвате множество бази (`CREATE DATABASE`, `USE DATABASE`), разпределените функции още не ги обхващат. Всяка база данни се нуждае от отделна кластър конфигурация. + ## Raft Консенсус Leader election и log репликация: diff --git a/docs/bg/schema.md b/docs/bg/schema.md index 6fb6e3f..9ae181b 100644 --- a/docs/bg/schema.md +++ b/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 <име>` преди миграционните команди. + ## Типове Полета | Тип | Описание | diff --git a/docs/bg/storage.md b/docs/bg/storage.md index 8c1eb0b..7fb8d76 100644 --- a/docs/bg/storage.md +++ b/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() diff --git a/docs/en/backup.md b/docs/en/backup.md index 56117fe..11349ff 100644 --- a/docs/en/backup.md +++ b/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//`). 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 `/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 diff --git a/docs/en/distributed.md b/docs/en/distributed.md index 206acdc..a4767d2 100644 --- a/docs/en/distributed.md +++ b/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: diff --git a/docs/en/schema.md b/docs/en/schema.md index ac90450..236dccc 100644 --- a/docs/en/schema.md +++ b/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 ` before executing migration commands. + ## Property Types | Type | Description | diff --git a/docs/en/storage.md b/docs/en/storage.md index 0f03295..8f1c15a 100644 --- a/docs/en/storage.md +++ b/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//`). 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()