Baradb/docs/bg/storage.md

Storage Engines

BaraDB предоставя множество storage двигатели, оптимизирани за различни модели на достъп.

LSM-Tree (Key-Value)

Основният storage engine с write-оптимизирана append-only лог структура.

Бележка за множество бази данни Всяка база данни има собствена изолирана директория (напр. data/databases/<име>/). Примерите по-долу използват ./data като placeholder — заменете с реалния път до вашата база.

Употреба

import barabadb/storage/lsm

var db = newLSMTree("./data/databases/default")
db.put("key1", cast[seq[byte]]("value1"))
let (found, value) = db.get("key1")
db.close()

Компоненти

• MemTable: В-памет сортиран буфер
• WAL: Write-ahead log за устойчивост
• SSTable: Сортирани string таблици на диска (v3 с CRC footer)
• Bloom Filter: Вероятностна проверка за принадлежност
• Compaction: Size-tiered стратегия с управление на нива
• MANIFEST: Атомичен каталог на активните SSTables
• Page Cache: LRU кеш с проследяване на hit rate

SSTable Формат (v3)

[Header] 36 байта
  magic:       uint32  (0x53535442 = "SSTB")
  version:     uint32  (3 = текуща)
  entryCount:  uint32
  level:       uint32
  indexOffset: uint64
  bloomOffset: uint64
  footerOffset: uint64

[Data Block]
  keyLen: uint32
  key:    bytes[keyLen]
  valueLen: uint32
  value:  bytes[valueLen]
  timestamp: uint64
  deleted: uint8

[Index Block]
  keyLen: uint32
  key:    bytes[keyLen]
  dataOffset: uint64

[Bloom Filter Block]
  bloomSize: uint32
  bloomData: bytes[bloomSize]

[Footer] 16 байта
  dataCrc32:  uint32  (CRC32 на Data Block)
  indexCrc32: uint32  (CRC32 на Index Block)
  bloomCrc32: uint32  (CRC32 на Bloom Block)
  reserved:   uint32  (трябва да е 0)

CRC footer-ът позволява независима проверка на всеки SSTable файл чрез verifySSTable(path).

MANIFEST Каталог

Файлът MANIFEST проследява всички активни SSTables атомично:

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

• Записва се атомично чрез MANIFEST.tmp + rename
• Чете се при стартиране за бързо зареждане
• Обновява се след всеки flush и compaction

WAL Ротация

Write-Ahead Log се ротира при достигане на 64MB:

wal/
  ├── wal.log          (активен сегмент)
  └── wal_archive/
      ├── wal.000001.log
      └── wal.000002.log

Ротацията се задейства:

• На всеки 1000 записа (лека проверка)
• При всеки flush() или checkpoint()

Storage Repair

Проверка и ремонт на storage:

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

# Пълен ремонт
./build/baradadb repair --data-dir=./data

Миграция на SSTable Версии

Пренаписване на legacy v1/v2 SSTables към v3:

./build/baradadb migrate --data-dir=./data

B-Tree Индекс

Подреден индекс за range сканиране и точково търсене.

Употреба

import barabadb/storage/btree

var btree = newBTreeIndex[string, string]()
btree.insert("key1", "value1")
let values = btree.get("key1")
let range = btree.scan("key_a", "key_z")

Write-Ahead Log (WAL)

Осигурява устойчивост на операциите за запис със сегментна ротация.

import barabadb/storage/wal

var wal = newWriteAheadLog("./wal")
wal.writePut(key, value, timestamp)
wal.sync()

Bloom Filter

Вероятностна структура от данни за бързи негативни проверки.

import barabadb/storage/bloom

var filter = newBloomFilter(10000, 0.01)
filter.add("key1")
if filter.mightContain("key1"):
  echo "евентуално съществува"

Memory-mapped I/O

Ефективен достъп до файлове чрез mmap.

import barabadb/storage/mmap

var mapped = openMmap("./data/file.dat")
let val = mapped.readUint32(0)