Baradb/docs/bg/backup.md

Backup и Възстановяване

BaraDB предоставя няколко стратегии за backup — от пълни snapshot-ове до инкрементални и online consistent backups.

⚠️ Настройка с множество бази данни BaraDB поддържа множество бази данни (CREATE DATABASE). Всяка база има собствена изолирана data директория (напр. data/databases/<име>/). Командите за backup, repair, checkpoint и migration работят върху една директория наведнъж. Ако използвате множество бази, пускайте командите за всяка база отделно или архивирайте цялата data/databases/ директория.

Архитектура

┌─────────────────────────────────────────┐
│  Data Directory                         │
│  ├── MANIFEST          (atomic catalog) │
│  ├── sstables/         (SSTable v3 CRC) │
│  │   ├── 1.sst                          │
│  │   └── 2.sst                          │
│  └── wal/                               │
│      ├── wal.log       (активен сегмент)│
│      └── wal_archive/  (ротирани сегменти
└─────────────────────────────────────────┘

Backup Инструмент

Backup инструментът е в src/barabadb/core/backup.nim. Компилирайте го преди употреба:

nim c -o:build/backup src/barabadb/core/backup.nim

SSTable Integrity (v3 CRC Footer)

Всеки SSTable файл, записан от BaraDB, включва CRC32 footer:

[Header] 36 байта
  magic, version(3), entryCount, level,
  indexOffset, bloomOffset, footerOffset
[Data Block]
[Index Block]
[Bloom Block]
[Footer] 16 байта
  dataCrc32, indexCrc32, bloomCrc32, reserved

Това позволява независима проверка на всеки SSTable:

# Чрез Nim API
import barabadb/storage/lsm
let (ok, msg) = verifySSTable("data/databases/default/sstables/1.sst")

Storage Repair (baradadb repair)

При съмнение за повреда, пуснете repair инструмента за конкретна база данни:

# 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.

{
  "version": 1,
  "sequence": 42,
  "createdAt": 1779103266,
  "sstables": [
    {"id": 1, "path": "sstables/1.sst", "level": 0, "minKey": "a", "maxKey": "z", "entryCount": 100}
  ]
}

Предимства:

• Консистентен изглед — няма 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 без спиране на сървъра:

./build/baradadb checkpoint --data-dir=./data/databases/default

Как работи:

1. Freeze на memtable (swap към immutable, нов memtable за writes)
2. Flush на frozen memtable към SSTable
3. Ротация на WAL
4. Запис на MANIFEST

Freeze-ът отнема < 1ms; flush-ът продължава паралелно с writes.

Backup Команди

Компилирайте backup инструмента първо: nim c -o:build/backup src/barabadb/core/backup.nim

Пълен Backup (tar.gz)

./build/backup backup --data-dir=./data/databases/default --output=backup_$(date +%s).tar.gz

Архивира цялата data директория на посочената база данни.

Инкрементален Backup

./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

./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 за всяка база данни:

# Преглед
./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

# Repair премества битите файлове и пуска WAL replay
./build/baradadb repair --data-dir=./data/databases/default

# Проверка на консистентност
./build/baradadb repair --data-dir=./data/databases/default --dry-run

Сценарий 2: Възстановяване от Backup (Единична База)

# Спиране на сървъра
# Разархивиране на backup в директорията на базата
tar -xzf backup_1234567890.tar.gz -C ./data/databases/default

# Рестарт — LSMTree зарежда от MANIFEST
./build/baradadb

Сценарий 3: Възстановяване на Всички Бази

Ако сте архивирали цялото data/databases/ дърво:

# 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. Стартиране на сървъра
./build/baradadb

Изисквания за Съхранение

Тип Backup	Размер	Честота	Задържане
Пълен tar.gz	~1× размер на данните	Седмично	4 седмици
Инкрементален	~0.05× размер на данните	На всеки час	24 часа
WAL архив	~0.02× размер на данните / ден	Непрекъснато	7 дни

Най-добри Практики

1. Пускайте repair след некоректно спиране — ./build/baradadb repair
2. Мигрирайте legacy SSTables — ./build/baradadb migrate
3. Тествайте възстановяването редовно — Backup, който не може да бъде възстановен, е безполезен
4. Използвайте incremental + checkpoint — За чести консистентни snapshot-ове
5. Съхранявайте backups извън локацията — S3, GCS или друг сървър
6. Следете MANIFEST sequence — Трябва да расте монотонно с flush-овете