Хранение данных (Storage Engine)

Goal

Объяснить как AngaraBase хранит данные на диске, какие форматы файлов используются и какие движки хранения доступны (или запланированы).

Pluggable storage architecture

AngaraBase использует модульную архитектуру хранения: движок (storage engine) отвечает за физическое размещение данных, а верхние уровни (SQL, транзакции, индексы) работают через унифицированный интерфейс. Это позволяет подключать разные движки для разных workloads без изменения SQL-уровня.

Текущий движок — Row-Store (строковое хранилище). В будущем планируются Column-Store и In-Memory Engine.

Row-Store (текущий движок)

Page-based heap storage

Данные хранятся в страницах фиксированного размера (16 KB). Каждая таблица представлена набором heap-страниц, в которых строки размещаются последовательно.

Slotted pages

Каждая страница устроена как slotted page:

┌─────────────────────────────────────┐
│ Page Header (LSN, checksum, flags) │
├─────────────────────────────────────┤
│ Slot Array → [offset₁, offset₂…] │
│ (растёт вниз ↓) │
│ │
│ свободное место │
│ │
│ (данные строк растут вверх ↑) │
│ Row₂ data │ Row₁ data │
└─────────────────────────────────────┘

Заголовок содержит LSN (log sequence number), контрольную сумму, page_type и флаги.
Slot array — массив указателей на строки внутри страницы. Это позволяет перемещать строки внутри страницы без изменения внешних ссылок (TID = page_id + slot_id).
Данные строк записываются от конца страницы к началу.

Типы страниц (page_type): 0 = data (heap), 1 = index (reserved), 2 = meta (reserved), 3 = overflow (reserved).

Page checksums

Каждая страница защищена контрольной суммой (CRC32C). При чтении страницы с диска checksum проверяется; при несовпадении сервер возвращает ошибку и не выдаёт повреждённых данных (fail-closed with diagnostics).

Форматы файлов

AngaraBase использует per-database файловую модель: каждая база данных — это пара файлов.

Расширение	Назначение	Magic
`.adb`	Heap-страницы с данными таблиц и индексами. Самодостаточный per-database storage file.	`APG1`
`.atl`	Transaction log (WAL) для конкретной базы данных. Per-database WAL.	`ADB1`

Индексы AngaraTree хранятся внутри .adb файла — для них зарезервирован page_type = 1 в заголовке страницы. Отдельного файла для индексов нет.

Source of truth: crates/angarabase/src/on_disk.rs, angarabook/src/operations/upgrade-and-migration.md.

Data directory layout

Каталог данных задаётся параметром storage.data_directory. Типичная структура:

data_directory/
├── VERSION # маркер инициализации (AVR1, 256 bytes, CRC32C)
├── base.adb # системная база данных (SysCatalog) — heap pages
├── base.atl # WAL системной базы данных
├── mydb.adb # пользовательская БД — heap pages + index pages
├── mydb.atl # WAL пользовательской БД
└── …

WAL не хранится в отдельных сегментированных файлах (как wal_000001 в PostgreSQL). В AngaraBase WAL — это один файл .atl на каждую базу данных, размещённый в том же каталоге data_directory.

Параметр storage.transaction_log_directory задаёт альтернативный каталог для .atl файлов (полезно для размещения WAL на отдельном диске).

Ключевые параметры

[storage]
data_directory = "/var/lib/angarabase/data"
transaction_log_directory = "/var/lib/angarabase/txlog"

Подробнее о параметрах — Конфигурация.

Column-Store (запланирован, v6)

Колоночный движок на основе Arrow/Parquet-like формата, ориентированный на аналитические запросы (OLAP). Данные хранятся по колонкам с поддержкой сжатия и vectorized scan.

Статус: не реализован, запланирован в roadmap v6.

In-Memory Engine (запланирован, v5 — AngaraMemory)

Движок для хранения данных в оперативной памяти. Запланированы три режима:

Режим	Описание
`volatile`	Данные только в памяти; теряются при перезапуске.
`logged`	Записи дублируются в WAL; восстановление при перезапуске.
`snapshotted`	Периодический snapshot на диск + WAL.

Статус: в разработке.

HTAP direction

Долгосрочная стратегия AngaraBase — HTAP (Hybrid Transactional/Analytical Processing):

Row-Store обслуживает OLTP (транзакционная нагрузка).
Column-Store обслуживает OLAP (аналитика).
Между ними — асинхронная репликация: данные из row-store преобразуются в колоночный формат для аналитических запросов.

Это позволит выполнять аналитику на свежих данных без ETL-конвейеров и без влияния на транзакционную производительность.

Связанные разделы

Концепции (что почитать дальше)

Транзакции и MVCC — как версии страниц связаны с MVCC и WAL.
Индексы — как B+tree-страницы укладываются поверх tablespace.
Каталог и метаданные — где physical-метаданные таблиц видны из SQL.

How-to (что сделать)

Конфигурация — настройки storage, wal, checkpoint.
Резервное копирование и восстановление — как переносить datadir между инстансами.
Crash recovery — поведение storage после аварийного завершения.
Диагностика — как смотреть IO/page-cache метрики.

Справочник

Системные представления sys.* — sys.tablespaces, sys.health для интроспекции состояния хранилища.
Известные ограничения и SQLSTATE — раздел STORAGE_* ошибок.

Keyboard shortcuts

AngaraBook