Архитектура AngaraBase

Этот документ даёт понимание внутреннего устройства AngaraBase на уровне, достаточном для принятия решений: выбор конфигурации, диагностика проблем, оценка применимости.

Подробная техническая спецификация: docs/01_ARCHITECTURE.md.

Многоуровневая архитектура

AngaraBase состоит из шести слоёв. Каждый слой имеет своё API и зависит только от слоёв ниже. Это позволяет заменять реализации (например, storage engine) без изменения остальных слоёв.

┌──────────────────────────────────────────────────────────────┐
│ TIER 1: CLIENT LAYER (Wire Protocol) │
│ │
│ • pgwire-протокол (совместимость с psql, JDBC, и др.) │
│ • connection pooling │
│ • async event loop │
└─────────────────────────┬────────────────────────────────────┘
 │
┌─────────────────────────┴────────────────────────────────────┐
│ TIER 2: SESSION / TRANSACTION LAYER │
│ │
│ • сессии и переменные сессии │
│ • управление транзакциями (BEGIN/COMMIT/ROLLBACK/SAVEPOINT) │
│ • уровни изоляции (READ COMMITTED, REPEATABLE READ) │
│ • блокировки и обнаружение deadlock'ов │
└─────────────────────────┬────────────────────────────────────┘
 │
┌─────────────────────────┴────────────────────────────────────┐
│ TIER 3: QUERY EXECUTION LAYER │
│ │
│ • парсинг SQL-запроса │
│ • семантическая валидация и проверка типов │
│ • планирование и оптимизация (AngaraPlan) │
│ • выполнение физического плана (AngaraFlow) │
└─────────────────────────┬────────────────────────────────────┘
 │
┌─────────────────────────┴────────────────────────────────────┐
│ TIER 4: CATALOG & TYPE SYSTEM │
│ │
│ • реестр таблиц, схем, баз данных │
│ • реестр типов, функций, операторов │
│ • реестр индексов (access methods) │
│ • системные представления sys.* │
└─────────────────────────┬────────────────────────────────────┘
 │
┌─────────────────────────┴────────────────────────────────────┐
│ TIER 5: STORAGE LAYER (Pluggable Storage) │
│ │
│ • row-store engine (OLTP baseline) │
│ • pluggable: in-memory и column-store (планируются) │
│ • индексы (AngaraTree: B+tree, BRIN) │
│ • Transaction Log (WAL) — журнал транзакций │
└─────────────────────────┬────────────────────────────────────┘
 │
┌─────────────────────────┴────────────────────────────────────┐
│ TIER 6: SYSTEM LAYER │
│ │
│ • буферный менеджер и page cache │
│ • метрики и телеметрия │
│ • восстановление после сбоев (crash recovery) │
│ • планировщик ресурсов (CPU, память, I/O) │
└──────────────────────────────────────────────────────────────┘

Что это значит для вас

• TIER 1: вы подключаетесь стандартным PostgreSQL-клиентом — ничего специального устанавливать не нужно.
• TIER 2: транзакции работают привычным образом — BEGIN, COMMIT, ROLLBACK, SAVEPOINT.
• TIER 3: SQL-запросы проходят через парсер, оптимизатор и исполнитель. EXPLAIN покажет план выполнения.
• TIER 4: метаданные о таблицах, типах и индексах доступны через системные представления sys.* (например, SELECT * FROM sys.tables).
• TIER 5: данные хранятся в pluggable storage engine. Сейчас — row-store; в будущих версиях можно будет выбирать движок при создании таблицы.
• TIER 6: буфер, метрики и восстановление — инфраструктурный слой, который работает прозрачно. Вы взаимодействуете с ним через конфигурацию и мониторинг.

Именованные компоненты

Ключевые подсистемы AngaraBase имеют собственные имена. Это упрощает диагностику, документацию и конфигурацию — когда вы видите имя в логах или метриках, вы знаете, к какой части системы оно относится.

Пример: если EXPLAIN показывает AngaraTree: Index Scan, это значит, что запрос использует B+tree-индекс. Если в логах появляется AngaraGC, это сборщик устаревших версий строк.

Модель данных

AngaraBase использует четырёхуровневую иерархию (аналогично MS SQL Server):

Instance (процесс angarabased)
 └─ Database
 └─ Schema
 └─ Table

• Instance — один запущенный процесс angarabased. Может содержать несколько баз данных.
• Database — изолированная база данных. Каждая БД имеет свои файлы данных, transaction log и настройки. Backup и restore работают на уровне отдельной базы.
• Schema — логическая группировка таблиц внутри базы (по умолчанию — public).
• Table — таблица с данными.

Пример:

angarabased (instance)
 ├─ Database "odoo_prod"
 │ ├─ Schema "public"
 │ │ ├─ Table "res_partner"
 │ │ ├─ Table "sale_order"
 │ │ └─ ...
 │ └─ Schema "staging"
 │ └─ ...
 ├─ Database "analytics"
 │ └─ Schema "public"
 │ └─ ...
 └─ System catalog (sys.*)

Каждая база данных независима: backup odoo_prod не затрагивает analytics, и наоборот.

Иерархия конфигурации

Настройки в AngaraBase применяются на трёх уровнях, от самого широкого к самому узкому:

Instance (angarabase.conf)
 └─ Database (ALTER DATABASE ... SET ...)
 └─ Session (SET ...)

Более узкий уровень переопределяет более широкий:

• Instance — настройки сервера (порт, лимиты памяти, пути к файлам). Часть из них требует перезапуска.
• Database — настройки конкретной базы (лимиты, параметры storage). Применяются без перезапуска.
• Session — настройки текущего подключения (SET timezone = 'Europe/Moscow'). Действуют до конца сессии.

Что это значит на практике

Архитектура AngaraBase спроектирована с учётом нескольких принципов, которые влияют на повседневную работу:

• Подключение стандартными инструментами. pgwire-совместимость означает, что вам не нужны специальные драйверы или библиотеки. psql, DBeaver, ваше приложение на Python или Java — всё подключается как к обычному PostgreSQL.

• Per-database изоляция. Каждая база данных — самостоятельная единица с точки зрения backup, restore и конфигурации. Это удобно для multi-tenant сценариев: каждый клиент может иметь свою БД с индивидуальными настройками и отдельным backup-расписанием.

• Явная диагностика. Системные представления sys.* дают доступ к метаданным и состоянию системы. Именованные компоненты (AngaraTree, AngaraPlan и др.) отражаются в EXPLAIN, логах и метриках — вы всегда знаете, какая часть системы задействована.

• Pluggable storage. Сейчас доступен row-store (оптимизирован для OLTP). В будущих версиях можно будет выбирать движок хранения при создании таблицы — in-memory для горячих данных, column-store для аналитики.

• Fail-closed поведение. Если конструкция SQL не поддерживается — вы получите явную ошибку с SQLSTATE-кодом, а не неожиданный результат. Это предсказуемо и безопасно для продакшена.

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

• Canonical architecture doc: docs/01_ARCHITECTURE.md — полная техническая спецификация.
• Хранение данных: concepts/storage-engine.md — row-store, страницы, pluggable storage.
• Обработка запросов: concepts/query-processing.md — парсер, планировщик, оптимизатор, исполнитель.
• Каталог и метаданные: concepts/catalog-and-metadata.md — SysCatalog и системные представления.