Architecture Overview

Этот документ — карта архитектуры AngaraBase as-is: какие крупные подсистемы существуют, как по ним течёт SQL-запрос и где лежат границы ответственности. Для пользовательского введения см. Архитектура AngaraBase.

Высокоуровневые компоненты

Компонент	Что делает
`angarabased`	Серверный адаптер: pgwire-протокол, listener, управление соединениями и сессиями
`angarabase` (engine core)	Parse/bind/plan/execute, транзакции, storage API, WAL/recovery primitives
`angara-cli`	CLI для администрирования (identity, ops через admin endpoint)
Operational surface	Конфигурация, метрики, логи, диагностические bundle, политики upgrade

Полный layering-контракт и правила зависимостей: Layering and Boundaries.

Поток запроса (упрощённо)

flowchart LR
    C[Client/Driver] -- pgwire --> S[angarabased adapter]
    S -- SQL + session ctx --> E[angarabase engine core]
    E --> P[Parse / Bind / Plan / Execute]
    P --> Sec[Security: RBAC + RLS]
    P --> T[Txn / MVCC]
    P --> St[Storage API]
    P --> Stat[Stats / CBO feedback]
    T --> Wal[WAL / Recovery]
    St --> Wal
    Wal --> IO[IO / fsync contract]
    E -- rows / errors --> S
    S -- pgwire responses --> C

Ключевые архитектурные решения

Область	Решение	Почему
MVCC	UNDO-log (история — отдельный append-only log; heap содержит только текущие версии)	Меньше bloat, нет тяжёлого `VACUUM`, детерминированный GC
Storage	Pluggable: row-store baseline + AngaraMemory; AngaraColumn в roadmap	HTAP-направление, разные tier’ы для разных нагрузок
Recovery	WAL-first, идемпотентный replay, fail-closed при отсутствии WAL целостности	Корректность важнее latency
Optimizer	Cost-based AngaraPlan + LEO feedback loop, robust planning	Устойчивость к ошибкам оценок
Execution	Volcano streaming (AngaraFlow) + vector path (AngaraVector)	Разделение по плановым формам, явное управление через `EXPLAIN`
Catalog	Persisted SysCatalog, DDL переживает restart	Предсказуемость для production
Security	6-слойная модель: TLS/Auth → RBAC → RLS → Break-glass → Audit chain → TDE	Defence-in-depth, fail-closed
Backup	Per-database, cold + online/PITR baseline	Multi-tenant изоляция
Distribution	Single-node engine; distributed SQL — горизонт major-веток	Concentration on correctness first

Границы и инварианты

angarabased (адаптер) не содержит SQL-логики — только pgwire framing, session ctx, маршрутизация в core.
angarabase core не знает о pgwire — общается через core API контракт.
Storage не делает MVCC visibility — только heap I/O. Visibility вычисляет MVCC layer.
Index не определяет видимость — только указывает на TID; visibility всегда recheck по heap.
Любая неподдерживаемая SQL-конструкция возвращает явный SQLSTATE (0A000 и др.) — никаких silent bypass.
Public API: pgwire + admin endpoint. Внутренние модули — implementation detail и могут меняться.

Архитектурные ограничения и do-not-block правила: Architecture Constraints.

Надёжность и физическая переносимость

Cold/offline backup и restore — full-instance copy на уровне data-directory (см. Backup/Restore).
Host migration — без pg_dump/pg_restore: copy + verify + start. Подробнее в Crash recovery.
Identity rehearsal — каждый release проходит rehearsal upgrade pipeline.
Page checksums + WAL CRC — обнаружение corruption на чтении/восстановлении.

Дополнительные материалы

Layering and Boundaries — официальный layering-контракт.
Архитектура AngaraBase (user-facing) — обзор для пользователей и DBA.
Project principles — идеологический компас проекта.

Keyboard shortcuts