AngaraBase

С чего начать

Выберите вход по своей роли:

Ключевые особенности

Совместимость с PostgreSQL без сюрпризов

• Стандартный pgwire-протокол: psql, JDBC, psycopg, node-postgres, pgx, Npgsql работают как с обычным PostgreSQL.
• Контрактное подмножество SQL: что поддерживается — поддерживается полностью; что не поддерживается — возвращает явный SQLSTATE (0A000 и др.), а не молчаливый bypass.
• Pinned-тесты совместимости (compat suite) как доказательство, а не «процент совместимости».

Подробнее: SQL compatibility overview.

Современный движок: MVCC через UNDO-log, а не через bloat

В отличие от PostgreSQL, AngaraBase хранит исторические версии строк в отдельном UNDO-логе (как Oracle/InnoDB), а не в самой таблице. В результате:

• heap-страницы содержат только текущие версии строк → меньше bloat;
• VACUUM в привычном смысле не нужен — старые версии очищает фоновый AngaraGC по чёткому контракту;
• видимость для транзакций определяется детерминированно по snapshot.

Подробнее: Транзакции и MVCC.

Pluggable storage с первого дня

• Row-store (baseline) — для OLTP.
• AngaraMemory — in-memory таблицы с тремя уровнями durability (none / logged / snapshotted) и hard row-cap.
• AngaraColumn — columnar storage для аналитики (в roadmap; HTAP-направление).

Выбор движка делается при CREATE TABLE ... WITH (storage='memory'|'row'|...).

Подробнее: Storage engine.

Cost-based оптимизатор и vectorized execution

• AngaraPlan — CBO с robust-планированием, устойчивым к ошибкам в оценках.
• AngaraStat — статистика: HLL для NDV, equi-height histograms, MCV (reservoir sampling).
• AngaraFlow — streaming-исполнение (Volcano).
• AngaraVector — vectorized путь для scan/filter/project/join/aggregate; режимы auto / force_vector / force_row. В EXPLAIN явно отмечается VectorHashJoin, VectorAgg и др.
• AngaraParallel — partitioned parallel join, DOP-капы (ANGARABASE_PARALLEL_DOP_CAP_*).

Подробнее: Query processing.

Многоуровневая защита с явными контрактами

Безопасность встроена в ядро, а не «прикручена» сверху. Шесть слоёв защиты, каждый с собственным контрактом:

1. Транспорт и идентичность — TLS, SCRAM, cert-аутентификация.
2. RBAC — кому вообще разрешено.
3. RLS v1 — какие строки видны и изменяемы.
4. Break-glass — единственный путь обхода RLS (даже SUPERUSER его не имеет), всегда с REASON, TTL и аудитом.
5. Audit chain — append-only, tamper-evident (SHA-256 chain).
6. TDE — шифрование страниц, WAL и audit-sink; fail-closed без ключа.

Подробнее: Security model.

Эксплуатация под предсказуемость

• Per-database backup и restore (cold + online/PITR baseline).
• Ясная диагностика: EXPLAIN/EXPLAIN ANALYZE, sys.* views (sys.identity, sys.health, sys.settings, sys.tables, sys.column_stats, angara_stat_activity, angara_stat_statements).
• Структурированное логирование, OpenTelemetry-style spans, USDT/eBPF probes.
• Метрики Prometheus: angara_* именованные подсистемы видно в логах, метриках и EXPLAIN.
• Native-пакеты RPM/DEB, init-first service start fence, systemd-юниты.

Подробнее: Operations runbooks.

Принципы проекта (явная позиция)

Полная декларация: Project principles.

Документация по разделам

Знакомство (Tutorials)

• Что такое AngaraBase
• Архитектура AngaraBase
• Quickstart

Концепции (Explanation)

• Хранение данных — row-store, страницы, slotted pages, pluggable storage
• Транзакции и MVCC — UNDO-log MVCC, изоляция, GC
• Индексы — AngaraTree (B+tree, BRIN), IndexStore
• Обработка запросов — AngaraPlan, AngaraStat, AngaraFlow, AngaraVector
• Каталог и метаданные — SysCatalog и sys.* views
• Жизненный цикл инстанса — init, startup, recovery, shutdown

SQL Reference (Reference)

• Обзор совместимости — политика, SQLSTATE-коды, vector execution
• Типы данных — поддерживаемые типы, casting, NULL
• DDL — CREATE/ALTER/DROP, индексы, ограничения
• DML — INSERT, UPDATE, DELETE, mutation policies
• Запросы — CTE, JOIN, агрегаты, ORDER BY
• Секционирование — RANGE/LIST partitioning, routing, pruning

Безопасность (How-to)

• Модель безопасности
• Аутентификация
• Авторизация (RBAC + RLS)
• Аудит
• Шифрование (TDE + клиентское)
• Break-glass
• Hardening runbook
• GOST-совместимость

Эксплуатация (How-to)

• Установка — portable archive, RPM/DEB, source build
• Конфигурация — TOML, env, sys.settings
• Резервное копирование и восстановление — cold + online/PITR
• Crash recovery — host migration, WAL replay
• Обновление версии
• Мониторинг — Prometheus, Grafana, health probes
• Диагностика — EXPLAIN, slow log, sys.*
• Логирование, Tracing, USDT/eBPF probes
• GC auto-tuning
• Error debug runbook (10 минут)
• GOST crypto setup
• Verify release artifacts

Operator deep-dives — runbooks (Reference)

• Operations overview
• Runbooks index
• Troubleshooting guide
• Disaster recovery playbook
• Performance tuning guide
• MVCC and GC operator minimum
• Diagnostics bundle runbook
• Security operations baseline
• Upgrade and migration
• Backup and restore (operator-level)
• Configuration schema reference
• Observability metrics checklist
• jemalloc heap profiling runbook
• Parallel runtime observability runbook
• Replication v2 operations guide
• Operational policies baseline
• Client compatibility baseline (operator)
• Testing and validation baseline
• Golden dataset management
• CI reproducibility contract
• Known issues baseline (operator)

Architecture (Reference)

• Architecture overview
• Layering and Boundaries

Справочник (Reference)

• Известные ограничения и SQLSTATE
• Глоссарий и именованные подсистемы
• Системные представления sys.*
• Совместимость клиентов
• Поддержка и сбор артефактов баг-репорта
• Generated reference (auto-generated registries)

История изменений

• AngaraBook changelog (highlights) — сжатая лента изменений с пользовательской точки зрения.

Сообщество и участие

Мы рады участникам сообщества:

• Нашли баг или regression? Соберите артефакты по Support flow и откройте issue.
• Хотите изменить поведение? Предложите RFC по процессу разработки проекта (внутренний контур).
• Хотите помочь с документацией? AngaraBook — documentation-as-code в этом же репозитории. Правила оформления: см. внутренний WRITING_RULES.md рядом с книгой.
• Хотите следить за разработкой? Следите за changelog и release notes.

О документации

AngaraBook построена на принципах Diátaxis:

• Tutorials (Знакомство) — обучение через действие, для новых пользователей.
• How-to guides (Безопасность / Эксплуатация) — рецепты для конкретных задач.
• Reference (SQL / Architecture / Справочник) — точное описание поведения.
• Explanation (Концепции) — почему всё устроено так, а не иначе.

Гарантии качества:

• Документация — часть кода: правится в одном репозитории, проходит ту же CI, что и движок.
• Любое заявленное SQL/ops-поведение проверяется pinned-тестами или явно помечается как roadmap.
• Anti-drift: версии команд, конфигурационные ключи и SQLSTATE-коды сверяются автоматически.
• Public-сборка проходит security gate: внутренние процессы и конфиденциальные ссылки не попадают в публичный портал.

Если вы заметили несоответствие документации и реального поведения — это баг документации; пожалуйста, сообщите.

AngaraBase v0.6.x · Linux x86_64/aarch64 · glibc >= 2.28

Что такое AngaraBase

AngaraBase — реляционная СУБД на Rust, совместимая с протоколом и подмножеством SQL PostgreSQL. Проектируется для нагрузок типа ERP/SaaS, где важны предсказуемое поведение, явные границы и отсутствие «магии».

• Платформа сервера: Linux x86_64 / aarch64 (glibc >= 2.28)
• Клиенты: любая платформа через стандартные PostgreSQL-драйверы
• Текущая ветка: 0.6.x

Что вы получаете прямо сейчас

Точные границы поддержки SQL и текущие ограничения зафиксированы в SQL compatibility overview и Known issues. AngaraBase не публикует «процент совместимости» — вместо этого приводит точный контракт.

Принципы

Совместимость с PostgreSQL

AngaraBase реализует pgwire-протокол как первичный API. С точки зрения клиента это обычный PostgreSQL endpoint:

psql "host=127.0.0.1 port=5432 user=angara_root dbname=base sslmode=verify-full"

Полный compat-контракт и smoke-сценарии: SQL compatibility overview.

Чем AngaraBase отличается от PostgreSQL

Кому подходит

• Командам ERP/SaaS (например, на базе Odoo), которым нужна предсказуемая PostgreSQL-совместимая БД с явным контрактом совместимости.
• DBA, ценящим явные границы поведения, а не «best-effort» совместимость.
• Инженерам, которым важно понимать, что именно поддерживается, и иметь reproducible-тесты как доказательство.
• Сообществу, готовому участвовать в формировании молодой СУБД.

Что AngaraBase не делает (на текущей ветке)

• Не предоставляет distributed SQL и multi-master HA — это горизонт следующих major-веток.
• Не реализует полный SQL PostgreSQL — только контрактное подмножество с явной границей.
• Не маскирует неподдержанные фичи — вы получаете явную ошибку с SQLSTATE.
• Не работает на не-Linux серверах. Клиенты — кросс-платформенные.

С чего начать

Ссылки

• Quickstart — собрать, запустить, выполнить первый SQL за несколько минут.
• Architecture — как устроена БД внутри.
• SQL reference — какой SQL поддерживается.
• Security model — модель безопасности.
• Operations — конфигурация и эксплуатация.
• Glossary — термины и именованные подсистемы.

Архитектура 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 и системные представления.

Quickstart (testing)

Goal

Поднять angarabased, подключиться через psql, выполнить базовый DDL/DML и убедиться, что pgwire работает.

Prerequisites

• Linux x86_64
• Один из вариантов установки:
• Rust toolchain (см. rust-toolchain.toml) для source build,
• или portable archive x86_64-unknown-linux-gnu (glibc >= 2.28).

Install from portable archive

mkdir -p /opt/angarabase
tar -xzf angarabase-0.6.3-x86_64-unknown-linux-gnu.tar.gz -C /opt/angarabase
/opt/angarabase/angarabase-0.6.3/bin/angarabase-server --version

If runtime glibc is below baseline (2.28), angarabase-server exits fail-closed with an explicit compatibility message.

Native package flow

For RPM/DEB deployments, service start is intentionally blocked before secure init:

angarabase-server --init /var/lib/angarabase --superuser admin --auth-mode scram --superuser-password-file /secure/path/pass.txt --require-auth
systemctl start angarabase

If you intentionally need trust bootstrap for isolated labs, it must be explicit:

angarabase-server --init /var/lib/angarabase --auth-mode trust --insecure-trust

Build

cargo build -p angarabase-server
cargo build -p angara-cli

Run server (local)

AngaraBase использует явную инициализацию инстанса (--init) перед обычным запуском.

Минимальный путь для тестирования (без ручного создания конфига):

1. Выполните одноразовую инициализацию в директории инстанса.

target/debug/angarabase-server --init /tmp/angarabase-instance --superuser angara_root --superuser-password 'change-me' --auth-mode scram

По умолчанию будет создано:

• data/ в /tmp/angarabase-instance/data
• txlog/ в /tmp/angarabase-instance/txlog
• конфиг angarabase.conf в /tmp/angarabase-instance/angarabase.conf

2. Запустите сервер:

target/debug/angarabase-server --config /tmp/angarabase-instance/angarabase.conf

В этом сценарии используется SCRAM bootstrap user angara_root. Для локального trust/no-auth режима можно явно запускать с --allow-insecure-no-auth.

SecurityContext note:

• In scram/cert modes, protected SQL execution requires session context.
• Minimal setup for tenant-scoped workloads:

SET SESSION CONTEXT 'app.tenant_id' = 'public';

Альтернативный путь (если вы хотите использовать существующий конфиг):

• --config <path> при --init читается как input-конфиг, если файл существует,
• и записывается как output-конфиг, если файл не существует.

Примеры:

# init using an existing config (input)
target/debug/angarabase-server --config ./angarabase.conf --init

# init and write a new config (output; file must not exist)
target/debug/angarabase-server --config /tmp/angarabase.conf --init /tmp/angarabase-instance

Для локальной разработки допускается shortcut:

target/debug/angarabase-server --config angarabase.conf --dev

--dev сохраняет auto-init поведение только для dev/test сценариев.

Connect with psql

psql "host=127.0.0.1 port=5432 user=angara_root dbname=base password=change-me sslmode=disable"

Smoke SQL

CREATE TABLE t (id INT PRIMARY KEY, v INT);
INSERT INTO t (id, v) VALUES (1, 10);
INSERT INTO t (id, v) VALUES (2, 20);
SELECT * FROM t ORDER BY id;

Restart check (DDL survives restart)

CREATE TABLE metadata (catalog) should survive restart.

1. Остановите сервер (Ctrl+C).
2. Запустите снова.
3. Проверьте, что таблица видна:

SELECT table_name FROM sys.tables WHERE table_name = 't';

Sys introspection (sys.*)

Примеры полезных запросов:

SELECT * FROM sys.identity;
SELECT * FROM sys.health;
SELECT * FROM sys.settings WHERE name IN ('server.addr','storage.data_directory');
SELECT * FROM sys.tables;
SELECT * FROM sys.columns WHERE table_name = 't';

Optional: SQL shutdown (fail-closed)

По умолчанию shutdown через SQL выключен. Чтобы включить (локально/для тестов):

export ANGARABASE_ALLOW_SQL_SHUTDOWN=1

После этого можно запросить shutdown из psql:

SELECT sys.request_shutdown();

If something fails

• Проверьте “Known issues”: ../reference/known-issues.md
• Для подключения клиентов (DBeaver и др.): ../reference/client-compatibility.md
• Для репорта багов соберите артефакты по ../reference/support.md.

Дальше

После того как сервер ответил psql -h 127.0.0.1 и базовый SELECT отработал, логичные следующие шаги:

• Что такое AngaraBase — продуктовый обзор: для чего проект, чем отличается от ванильного PostgreSQL.
• Обзор совместимости SQL — что из стандарта можно использовать прямо сейчас.
• Конфигурация — как поднять сервер не из дефолтов, а под свой сценарий.
• Модель безопасности — прежде чем пускать кого-либо ещё, кроме себя.

Подключение клиентов: psql, Python, JDBC

Что вы получите за 15 минут

После этого туториала у вас будут три рабочих способа подключения к локально запущенному инстансу AngaraBase:

1. psql — интерактивная консоль PostgreSQL.
2. Python через psycopg[binary] — типичный скрипт приложения.
3. JDBC через стандартный org.postgresql:postgresql — типичный Java/Kotlin/Scala-стек.

Все три способа работают через стандартный pgwire-протокол: AngaraBase представляется клиентам как PostgreSQL, поэтому никаких специальных драйверов не требуется.

Prerequisites

• AngaraBase, поднятый локально по Quickstart. Считаем, что сервер слушает 127.0.0.1:5432, есть пользователь angara и база angara_demo.
• Установленный psql (любая версия PostgreSQL ≥ 13).
• Python 3.10+ (для шага 2).
• JDK 17+ и Maven/Gradle (для шага 3).

Проверьте, что сервер отвечает:

psql --version
# psql (PostgreSQL) 16.4

ss -ltnp 'sport = 5432'
# LISTEN ... 127.0.0.1:5432 ...

Если порт не слушается — вернитесь к Quickstart и убедитесь, что angarabased запустился без ошибок.

Шаг 1. psql — интерактивная консоль

1.1. Подключение

psql 'postgresql://angara@127.0.0.1:5432/angara_demo'

Пароль (если задан) — по подсказке. Признак успеха: приглашение angara_demo=>.

1.2. Минимальный сценарий: создать таблицу, вставить, выбрать

-- Внутри psql:
CREATE TABLE products (
    id    BIGINT PRIMARY KEY,
    name  TEXT NOT NULL,
    price NUMERIC(10, 2) NOT NULL
);

INSERT INTO products (id, name, price) VALUES
    (1, 'Coffee', 4.50),
    (2, 'Tea',    3.00);

SELECT id, name, price FROM products ORDER BY id;

Ожидаемый вывод:

 id | name   | price
----+--------+-------
  1 | Coffee |  4.50
  2 | Tea    |  3.00
(2 rows)

1.3. Полезные \-команды

1.4. Если что-то пошло не так

• could not connect to server: Connection refused — сервер не запущен или слушает не 127.0.0.1. Проверьте ss -ltnp 'sport = 5432' и логи angarabased.
• authentication failed for user "angara" — пароль не задан или не совпадает. См. Аутентификация.
• feature_not_supported (0A000) — вы попали в SQL-конструкцию, которую AngaraBase не поддерживает. Это явный fail-closed контракт; см. Известные ограничения и SQLSTATE.

Шаг 2. Python через psycopg

2.1. Установка драйвера

Используем psycopg версии 3 (бинарный wheel — без локальной компиляции):

python3 -m venv .venv
source .venv/bin/activate
pip install 'psycopg[binary]>=3.1,<4'

2.2. Минимальный скрипт

Создайте файл connect_demo.py:

import psycopg

DSN = "postgresql://angara@127.0.0.1:5432/angara_demo"

with psycopg.connect(DSN) as conn:
    with conn.cursor() as cur:
        cur.execute(
            "INSERT INTO products (id, name, price) VALUES (%s, %s, %s)",
            (3, "Espresso", 4.25),
        )
        cur.execute("SELECT id, name, price FROM products ORDER BY id")
        for row in cur.fetchall():
            print(row)
    conn.commit()

Запуск:

python3 connect_demo.py

Ожидаемый вывод:

(1, 'Coffee', Decimal('4.50'))
(2, 'Tea', Decimal('3.00'))
(3, 'Espresso', Decimal('4.25'))

2.3. Что важно знать про Python-клиент

• Параметризованные запросы обязательны. Не подставляйте значения через f"...{value}..." — это путь к SQL-инъекциям. psycopg подставляет параметры на стороне драйвера через серверный prepared statement.
• with conn: и conn.commit() — разные вещи. Контекст-менеджер with conn: гарантирует закрытие соединения, но не делает автокоммит. Транзакция фиксируется только явным conn.commit().
• AngaraBase предсказуемо возвращает SQLSTATE. Перехватывайте psycopg.errors.FeatureNotSupported и проверяйте e.diag.sqlstate == "0A000", чтобы корректно обрабатывать неподдерживаемые конструкции (контракт fail-closed).

Шаг 3. JDBC через org.postgresql:postgresql

3.1. Зависимость

Maven (pom.xml):

<dependency>
  <groupId>org.postgresql</groupId>
  <artifactId>postgresql</artifactId>
  <version>42.7.4</version>
</dependency>

Gradle (build.gradle.kts):

dependencies {
    implementation("org.postgresql:postgresql:42.7.4")
}

3.2. Минимальный класс

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;

public class ConnectDemo {
    public static void main(String[] args) throws Exception {
        String url = "jdbc:postgresql://127.0.0.1:5432/angara_demo";
        java.util.Properties props = new java.util.Properties();
        props.setProperty("user", "angara");
        props.setProperty("preferQueryMode", "simple");

        try (Connection conn = DriverManager.getConnection(url, props)) {
            conn.setAutoCommit(false);

            try (PreparedStatement ps = conn.prepareStatement(
                    "INSERT INTO products (id, name, price) VALUES (?, ?, ?)")) {
                ps.setLong(1, 4L);
                ps.setString(2, "Cappuccino");
                ps.setBigDecimal(3, new java.math.BigDecimal("4.75"));
                ps.executeUpdate();
            }

            try (PreparedStatement ps = conn.prepareStatement(
                    "SELECT id, name, price FROM products ORDER BY id");
                 ResultSet rs = ps.executeQuery()) {
                while (rs.next()) {
                    System.out.printf(
                            "%d %s %s%n",
                            rs.getLong("id"),
                            rs.getString("name"),
                            rs.getBigDecimal("price"));
                }
            }

            conn.commit();
        }
    }
}

3.3. Что важно знать про JDBC-клиент

• preferQueryMode=simple — рекомендованный default для AngaraBase. Это отключает агрессивный probe-режим extended-protocol, который драйвер использует для совместимости с PostgreSQL-расширениями. AngaraBase реализует pgwire по контракту, и часть extended-protocol-проверок не нужна.
• assumeMinServerVersion=9.0 — добавьте в props, если планируете работать через DBeaver/DataGrip; см. Совместимость клиентов → DBeaver.
• Транзакции и setAutoCommit(false). AngaraBase реализует MVCC через UNDO-log; явные транзакции дают предсказуемый snapshot. Не оставляйте долгие транзакции открытыми — это замедляет AngaraGC.

Дальше

• Обзор совместимости SQL — что именно из стандарта SQL доступно через все три клиента.
• Совместимость клиентов — справочник по конкретным GUI-инструментам и драйверам (DBeaver, IntelliJ DataGrip, и т.д.).
• Модель безопасности — как настроить TLS, SCRAM и аутентификацию по сертификату для production-подключений.
• Известные ограничения и SQLSTATE — какие коды клиент должен ожидать вместо «магических» значений.

Контракты в AngaraBase

Goal

Объяснить, что в AngaraBase понимается под словом «контракт», какие уровни контрактов существуют и какими механизмами они соблюдаются. Эта страница — для пользователей, DBA и новых контрибьюторов: чтобы при чтении документации, кода или сообщений об ошибках было понятно, на какие гарантии можно полагаться, а какие — явно вне контракта.

Что мы понимаем под контрактом

Контракт в AngaraBase — это явное обещание о наблюдаемом поведении компонента: что он принимает на вход, что возвращает, какие гарантии даёт и как ведёт себя при нарушении границ. Контракт не «лучшие намерения» и не «как обычно работает» — это формализованная договорённость, которую обязаны соблюдать обе стороны: реализация и вызывающий код (или клиент).

У контракта три ключевых свойства:

1. Явность. Контракт зафиксирован в одном каноническом источнике — не в чате, не в коде комментария, не в «общем понимании команды».
2. Проверяемость. Соблюдение контракта подтверждается автоматически: тестами, типами, метриками, lint-проверками.
3. Fail-closed. При нарушении границы контракта система возвращает явную ошибку (с известным кодом), а не «как-нибудь продолжает работать».

Если что-то в системе не покрыто контрактом, это явно помечается как roadmap, experimental или known limitation. Поведение вне контракта может измениться без deprecation-цикла.

Уровни контрактов

В AngaraBase есть несколько уровней контрактов, каждый со своим источником истины и способом проверки.

1. SQL-контракт (внешний, для пользователя)

Что поддержано — поддержано полностью. Что не поддержано — возвращает явный SQLSTATE (0A000 feature_not_supported и др.), а не молчаливый bypass или искажённый результат.

• Источник: SQL — обзор совместимости, Известные ограничения и SQLSTATE.
• Проверка: pinned compat suite, регрессионные тесты на каждый зафиксированный SQLSTATE.
• Что это значит на практике: клиент может ловить psycopg.errors.FeatureNotSupported и точно знать, что попал в задокументированное ограничение, а не в баг.

2. Конфигурационный контракт

Каждый ключ конфига имеет тип, значение по умолчанию, диапазон допустимых значений и поведение при отсутствии или некорректном значении.

• Источник: Configuration, Configuration schema reference.
• Проверка: парсер отвергает неизвестные/некорректные ключи на старте (fail-closed), а не молча игнорирует.
• Изменение семантики ключа — через deprecation-цикл (см. WRITING_RULES.md §9a).

3. Operational контракт

Метрики, USDT-зонды, имена sys.* view, формат backup/restore, формат логов и runbook-вывода — всё это публичные имена, на которые завязан мониторинг и автоматизация оператора.

• Источник: System tables, Observability metrics checklist, Backup and restore, USDT/eBPF probes.
• Принцип: каждая ресурсная граница (RAM-бюджет буфер-пула, лимит write-set транзакции, snapshot age и т.д.) обязана иметь Prometheus-метрику и явное fail-closed поведение при нарушении. Граница без наблюдаемости — это не контракт.

4. Внутренние API-контракты (для контрибьютора)

Каждая подсистема ядра имеет публичный Rust-trait, который определяет её семантику: TableEngine, PageProvider, TransactionLogSink, StorageIo и др. Без реализации контракта код не соберётся — это «honest checked promise», а не «честное слово разработчика».

• Источник: doc-comments на trait-ах, Architecture overview, API Boundaries.
• Проверка: компилятор Rust + property-tests на инварианты + layering lint (Core не зависит от Adapters/Tooling).

5. Документационный контракт (anti-drift)

Документация — часть кода. Любое изменение публичного контракта (SQL surface, конфиг-ключи, метрики, SQLSTATE, имена сабсистем, защитные дефолты, порядок init/upgrade) обязательно сопровождается изменением AngaraBook в том же PR.

• Источник: WRITING_RULES.md §8 — Anti-drift contract.
• Проверка: pre-commit / CI прогоняют tools/docs/lint_angarabook_public.py, tools/docs/check_public_build_security.py и помечают расхождение как блокирующее.

Как мы соблюдаем контракты

Контракт без механизма соблюдения — декларация. В AngaraBase используется несколько слоёв принуждения, которые работают вместе.

Type system как первый рубеж

• Result<T, Error> вместо panic. unwrap() / expect() в production-коде запрещены.
• Bounded generics и trait-объекты вместо dynamic dispatch там, где инвариант можно зафиксировать на уровне типов.
• No-panic policy: сервер не падает из-за пользовательского ввода — он возвращает SQLSTATE.

Restrictive by default + fail-closed

Каждый компонент с ресурсной границей обязан определить:

• свою границу (например, buffer_pool_size_mb, txn_max_write_set_mb, max_concurrent_queries),
• поведение при её нарушении (явная ошибка с известным SQLSTATE),
• реакцию вызывающего кода (Reaction Propagation Contract).

Нет границы и нет fail-closed поведения — нет merge.

Pinned tests и golden datasets

Контракт SQL-совместимости и совместимости клиентов подтверждается pinned-тестами, а не «процентом совместимости». Если тест зафиксирован — изменение поведения требует либо обновления теста с обоснованием, либо отката изменения.

Подробнее: Testing and validation baseline, Golden dataset management, CI reproducibility contract.

Deprecation-цикл

Когда контракт выводится из обращения, он не исчезает молча. Применяется единый цикл: Active → Deprecated → Removed, минимум один major-релиз между объявлением Deprecated и Removed; до v1.0 — минимум две minor-точки. Каждое изменение фазы — атомарный PR (код + AngaraBook + Migration steps).

Полный регламент: WRITING_RULES.md §9a — Deprecation policy. Public-список всех deprecated/removed контрактов: Известные ограничения и SQLSTATE.

Security gate как fail-closed для документации

Что это даёт пользователю

• Предсказуемость поведения. Если поведение задокументировано — оно стабильно в рамках мажора. Если задокументировано как ограничение со SQLSTATE — оно вернёт именно этот SQLSTATE, а не «иногда работает».
• Безопасный код клиента. Можно ловить конкретные SQLSTATE и строить логику ретраев / обработки ошибок без эвристик и парсинга текстовых сообщений.
• Понятный апгрейд. Изменение поведения публичного контракта проходит явный deprecation-цикл с migration-шагами; вы заранее видите, что и когда поменяется.
• Наблюдаемость гарантий. Каждая ресурсная граница имеет метрику; вы видите утилизацию и реджекты до того, как они станут инцидентом.

Что это даёт разработчику и контрибьютору

• Контракт компилятора, а не review-комментария. Если инвариант можно закодировать в trait или тип — он кодируется. Code review ловит то, что компилятор поймать не может.
• Один источник истины на тип знания. Не нужно «искать актуальную правду по нескольким документам»: для каждого слоя контракта есть один canonical owner.
• Предсказуемая работа с долгом. Deprecated-контракт фиксируется в reference/known-issues.md, а если он не закрывается одним PR — в registry технического долга со статусом scheduled <target-train>.
• Anti-drift в одном PR. Меняешь поведение — обновляешь AngaraBook здесь же. Не «доработать docs позже».

Что не является контрактом

Чтобы избежать ложных ожиданий, явно: контрактом не считаются:

• внутренние имена модулей, файлов и приватных функций ядра (могут меняться при рефакторинге без deprecation);
• поведение фич с frontmatter status: experimental или CLI-флагами --experimental-* — они никогда не считались стабильными;
• тексты сообщений об ошибках (контракт — SQLSTATE и его смысл, не текст);
• не задокументированные побочные эффекты, замеченные эмпирически («у меня работает, если…»);
• бенчмарки и численные значения латентности — это observability, а не обещание производительности (performance-claim требует pinned benchmark, см. tools/perf_pack/).

Если вы опираетесь на что-то из этого списка в продакшене — это технический долг на стороне клиента, и очередное обновление AngaraBase его раскроет.

Links

• Project Principles §1 — Restrictive by Default — фундамент fail-closed подхода (см. также docs/00_PROJECT_PRINCIPLES.md в internal-сборке).
• SQL — обзор совместимости — SQL-контракт.
• Известные ограничения и SQLSTATE — public-список границ и deprecated/removed контрактов.
• Configuration schema reference — конфигурационный контракт.
• Architecture overview, API Boundaries — внутренние API-контракты и layering.
• Observability metrics checklist — наблюдаемость как часть контракта.
• WRITING_RULES.md — документационный контракт (anti-drift, deprecation policy).

Хранение данных (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 файловую модель: каждая база данных — это пара файлов.

Индексы 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)

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

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

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_* ошибок.

Транзакции и MVCC

AngaraBase обеспечивает конкурентный доступ к данным через MVCC (Multi-Version Concurrency Control). Транзакции гарантируют атомарность изменений, а MVCC позволяет читателям и писателям работать одновременно без взаимных блокировок.

Основы транзакций

Управление транзакциями

BEGIN; -- начать явную транзакцию
SAVEPOINT sp1; -- создать точку сохранения
ROLLBACK TO SAVEPOINT sp1; -- откатить до точки сохранения
COMMIT; -- зафиксировать транзакцию
ROLLBACK; -- откатить всю транзакцию

Autocommit

По умолчанию AngaraBase работает в режиме autocommit: каждый отдельный SQL-оператор выполняется как самостоятельная транзакция. Если оператор завершается успешно — результат фиксируется автоматически, при ошибке — откатывается.

Для операций, затрагивающих несколько строк или таблиц, используйте явные транзакции (BEGIN / COMMIT), чтобы объединить изменения в единую атомарную единицу.

MVCC: версионирование строк

Ключевая идея MVCC — читатели не блокируют писателей, писатели не блокируют читателей. Это достигается за счёт хранения нескольких версий каждой строки.

Метаданные версий

Каждая версия строки содержит два служебных поля:

Правило видимости

Версия строки видна транзакции со snapshot S, если выполняются оба условия:

1. created_commit <= S — версия создана до или в момент snapshot
2. Версия не удалена, или deleted_commit > S — удаление произошло после snapshot

Операции записи

• INSERT — создаёт новую версию строки с created_commit = текущий epoch
• UPDATE — не меняет строку на месте. Вместо этого: помечает текущую версию как удалённую (deleted_commit = текущий epoch) и создаёт новую версию с обновлёнными данными
• DELETE — помечает версию как удалённую (deleted_commit = текущий epoch)

Уровни изоляции

Каждая транзакция получает snapshot — фиксированное представление данных на определённый момент времени.

READ COMMITTED (по умолчанию)

Snapshot обновляется перед каждым оператором. Транзакция видит все данные, зафиксированные до начала текущего оператора. Это рекомендуемый уровень изоляции для большинства задач.

SET TRANSACTION ISOLATION LEVEL READ COMMITTED;

REPEATABLE READ

Snapshot фиксируется в момент BEGIN и не меняется до конца транзакции. Все операторы внутри транзакции видят одно и то же состояние данных.

SET TRANSACTION ISOLATION LEVEL REPEATABLE READ;

SERIALIZABLE

С версии 0.6.4.4 AngaraBase реализует полноценный SERIALIZABLE (SSI) уровень изоляции. В режиме SERIALIZABLE аномалии write skew и phantoms предотвращаются через механизм SIREAD-блокировок и отслеживание rw-антизависимостей. Транзакции, нарушающие сериализуемость, прерываются с кодом 40001.

SET TRANSACTION ISOLATION LEVEL SERIALIZABLE;

Блокировки

Операции чтения

Чтение использует MVCC snapshot и не требует блокировок. Читатель никогда не ждёт писателя и наоборот.

Операции записи (Lock-Free DML)

Писатели используют атомарные операции (Compare-And-Swap) для установки версий на уровне строк, что обеспечивает lock-free бесконфликтные изменения. Блокировки в классическом виде больше не удерживаются.

DDL-операции

Операции изменения схемы (CREATE TABLE, ALTER TABLE, DROP TABLE) захватывают table-level locks на время выполнения.

Обнаружение deadlock

AngaraBase обнаруживает взаимные блокировки (deadlock) с помощью:

• Timeout — если транзакция ожидает блокировку дольше заданного порога, она прерывается
• Victim selection — при обнаружении цикла система выбирает транзакцию-жертву для отката
• Deterministic lock ordering — внутренняя стратегия упорядочивания блокировок для снижения вероятности deadlock

Сборка мусора (AngaraGC)

Со временем в хранилище накапливаются старые версии строк, которые больше не видны ни одной активной транзакции. Подсистема AngaraGC отвечает за их очистку.

Механизм работы

1. GC watermark — вычисляется как минимальный snapshot среди всех активных транзакций: min(active_snapshots)
2. Версии строк с deleted_commit < watermark безопасны для удаления — ни одна активная транзакция не может их увидеть
3. Очистка выполняется фоновым процессом без остановки обработки запросов
4. Bounded slices — GC обрабатывает данные порциями фиксированного размера, чтобы не вызывать всплески задержки
5. Epoch Reaper — фоновый процесс (начиная с версии 0.6.5.24), который предотвращает зависание GC watermark из-за разорванных соединений или зависших сессий.

Отличие от PostgreSQL

В AngaraBase нет autovacuum в привычном понимании. Используется гибридный дизайн с epoch-based watermark (как в Oracle/InnoDB), что позволяет точнее контролировать момент очистки.

Рекомендации

• Используйте READ COMMITTED (уровень по умолчанию) для большинства рабочих нагрузок
• Избегайте долгоживущих транзакций — они удерживают GC watermark и не позволяют очистить старые версии строк, что увеличивает потребление дискового пространства
• При использовании REPEATABLE READ помните о возможности write skew. Если нужна строгая сериализуемость, используйте явные блокировки (SELECT ... FOR UPDATE)

MVCC state при crash recovery

При перезапуске после аварийного завершения AngaraBase восстанавливает состояние MVCC из transaction log (WAL).

Что восстанавливается

1. Committed transactions — транзакции, которые успели записать COMMIT в WAL
2. Aborted transactions — незавершённые транзакции помечаются как aborted
3. MVCC visibility — информация о том, какие версии строк видны для каждого commit epoch
4. Transaction counters — текущий commit epoch и другие счётчики

Процесс восстановления

1. WAL scan — сканирование файлов transaction log в хронологическом порядке
2. MVCC replay — восстановление in-memory структур MVCC из записей в WAL
3. Cleanup — пометка незавершённых транзакций как aborted

Ограничения

• Backend requirement: восстановление MVCC работает только с transaction_log.backend = "file_bin"
• Memory rebuild: MVCC state восстанавливается в памяти, что может занять время при большом объёме WAL
• Read-your-writes: сразу после restart незавершённые транзакции не видны (помечены как aborted)

Мониторинг восстановления

-- Проверить режим восстановления
SELECT recovery_mode FROM sys.identity;

-- Проверить состояние системы после recovery
SELECT txn_commit_epoch_current FROM sys.health;

Возможные значения recovery_mode:

• "normal" — обычный старт без восстановления
• "crash_recovery" — восстановление после аварийного завершения
• "forced_takeover" — принудительный захват instance lease

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

• Storage engine — устройство хранилища и формат страниц
• Instance Lifecycle — жизненный цикл инстанса и crash recovery
• Crash Recovery — операционные процедуры восстановления
• Справочник SQL — синтаксис SQL-операторов

Индексы (Indexes)

Goal

Объяснить какие типы индексов доступны в AngaraBase, когда их использовать и как они взаимодействуют с MVCC.

AngaraTree — index engine

AngaraTree — индексный движок AngaraBase. Индексы хранятся в .atl-файлах отдельно от heap-данных.

B+tree (default)

Основной тип индекса. Подходит для equality- и range-запросов; ключи хранятся в детерминированном порядке.

-- Создание B+tree индекса (эквивалентные формы):
CREATE INDEX idx_name ON orders (customer_id);
CREATE INDEX idx_name ON orders USING btree (customer_id);

B+tree индекс ускоряет:

• Точные совпадения: WHERE customer_id = 42
• Диапазоны: WHERE created_at >= '2026-01-01' AND created_at < '2026-02-01'
• Сортировку: ORDER BY customer_id

BRIN (Block Range Index)

Компактный индекс для данных с естественным порядком (append-only, time-series). BRIN хранит min/max значения для диапазонов heap-страниц, что позволяет пропускать целые блоки при сканировании.

CREATE INDEX idx_ts ON events USING brin (created_at);

Поддерживаемые типы ключей:

Как BRIN работает: индекс выступает как accelerator path — сначала отсекаются блоки, не содержащие нужных значений, затем выполняется heap fetch с MVCC predicate recheck. BRIN не гарантирует точность — он только сужает область поиска.

Метрика эффективности: angara_brin_range_efficiency показывает долю блоков, пропущенных благодаря BRIN. Чем ближе к 1.0, тем эффективнее индекс (данные хорошо кластеризованы).

Hash / Bloom

Зарезервированы как optional/future index types. На данный момент не реализованы.

Индексы и MVCC

Индекс хранит ссылки TID (page_id, slot_id) на строки в heap. Видимость строки определяется не индексом, а MVCC-слоем при чтении heap-страницы:

1. Запрос обращается к индексу → получает набор TID.
2. По каждому TID читается heap-страница.
3. MVCC-слой проверяет видимость версии строки для текущей транзакции.

Следствие: индекс может содержать ссылки на невидимые (устаревшие) версии строк. Это нормально — такие записи фильтруются при heap fetch.

IndexStore — персистентные вторичные индексы

AngaraBase поддерживает персистентные вторичные индексы для RowStore таблиц через IndexStore.

Как работает

• CREATE INDEX строит индекс через полный скан таблицы (build_from_rows) и сохраняет результат.
• DML (INSERT/DELETE) автоматически обновляет все индексы таблицы — fail-closed: если обновление индекса не удалось, heap mutation откатывается.
• Оптимизатор использует индекс для WHERE col = value запросов (O(log N) вместо O(N) seq_scan).

Ресурсные ограничения

Наблюдаемость

Текущие ограничения

Попытка создать неподдерживаемый индекс возвращает SQLSTATE 0A000 (feature_not_supported).

Когда создавать индексы

Рекомендуется:

• На колонках, часто используемых в WHERE, JOIN ON, ORDER BY.
• BRIN — на time-series колонках таблиц с append_only = true, где данные вставляются в порядке возрастания ключа.

Не рекомендуется:

• На таблицах с малым количеством строк (full scan будет быстрее).
• На колонках с очень низкой селективностью (например, boolean-флаги).
• Создание множества индексов на одной таблице замедляет INSERT/UPDATE/DELETE.

Используйте EXPLAIN ANALYZE для проверки, использует ли оптимизатор индекс. Подробнее — Обработка запросов.

Проверка целостности индекса

Для offline-проверки целостности B+tree индекса доступна функция validate():

SELECT angara_index_validate('idx_name');

Рекомендуется выполнять после аварийного завершения или восстановления из backup.

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

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

• Обработка запросов — как оптимизатор выбирает и комбинирует индексы.
• Хранение данных — как страницы B+tree ложатся в tablespace.
• Транзакции и MVCC — почему обновление индексов под нагрузкой требует MVCC-видимости.

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

• DDL: CREATE/DROP INDEX — синтаксис создания и удаления индексов.
• Диагностика — как через EXPLAIN ANALYZE и sys.* понять, используется ли индекс.

Справочник

• Типы данных — какие типы поддерживаются как ключи индексов.
• Системные представления sys.* — sys.indexes, sys.column_stats для анализа покрытия.

Обработка запросов (Query Processing)

Goal

Объяснить как AngaraBase обрабатывает SQL-запросы: от текста до результата. Полезно для понимания EXPLAIN-планов и диагностики производительности.

Pipeline overview

Каждый SQL-запрос проходит четыре стадии:

SQL text ──▸ Parsing ──▸ Planning ──▸ Optimization ──▸ Execution ──▸ Result

1. Parsing: SQL → AST

Парсер преобразует текст запроса в абстрактное синтаксическое дерево (AST). AngaraBase использует PostgreSQL-совместимый SQL-диалект.

Если синтаксис не поддерживается, сервер возвращает SQLSTATE 0A000 (feature_not_supported) с описанием неподдерживаемой конструкции.

2. Planning: AST → logical plan

На этапе планирования выполняется:

• Name resolution — сопоставление имён таблиц, колонок и функций с объектами каталога.
• Type checking — проверка типов и автоматическое приведение (coercion) при необходимости.

Результат — логический план, описывающий что нужно сделать, но не как.

3. Optimization (AngaraPlan)

Оптимизатор AngaraPlan преобразует логический план в физический, выбирая наиболее эффективную стратегию выполнения.

Cost-based optimizer (CBO): решения принимаются на основе статистики (AngaraStat) — количество строк, распределение значений, наличие индексов.

Ключевые решения оптимизатора:

Robust planning: оптимизатор устойчив к ошибкам в оценках — при значительном расхождении между estimated и actual rows план остаётся работоспособным (не приводит к worst-case поведению).

LEO (Learning Optimizer): feedback loop — после выполнения запроса фактическая статистика используется для улучшения будущих оценок.

4. Execution (AngaraFlow)

Исполнитель AngaraFlow выполняет физический план в iterator/streaming модели (Volcano): каждый оператор запрашивает следующую строку у дочернего оператора.

Основные операторы:

AngaraStat (статистика)

Оптимизатор использует статистику из системных таблиц для оценки стоимости планов.

sys.table_stats

sys.column_stats

Управление уровнем статистики

ALTER TABLE t SET (stats_level_max = 2);

Более высокий уровень даёт оптимизатору больше информации, но увеличивает время сбора статистики.

Диагностика запросов

EXPLAIN

Просмотр плана выполнения без выполнения запроса:

EXPLAIN SELECT * FROM orders WHERE customer_id = 42;

Варианты:

EXPLAIN ANALYZE SELECT ...; -- выполняет запрос, показывает actual rows/time
EXPLAIN (BUFFERS) SELECT ...; -- + статистика чтения страниц
EXPLAIN (FORMAT JSON) SELECT ...; -- вывод в JSON

Системные представления

Slow query log

Включается через переменную окружения:

ANGARABASE_LOG_MIN_DURATION_MS=100 # логировать запросы дольше 100 мс
ANGARABASE_LOG_QUERY_TEXT=1 # включить текст запроса в лог

Подробнее — Диагностика.

Future

Запланированные улучшения обработки запросов:

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

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

• Индексы — как оптимизатор выбирает индекс для SELECT/UPDATE.
• Каталог и метаданные — где хранится статистика, которой пользуется планировщик.
• Транзакции и MVCC — как уровень изоляции влияет на план выполнения.

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

• Диагностика — EXPLAIN ANALYZE, slow-query log, как читать план.
• Tracing — распределённая трассировка фаз parse → plan → execute.
• Логирование — ANGARABASE_LOG_QUERY_TEXT, ANGARABASE_LOG_MIN_DURATION_MS.

Справочник

• SQL Overview — что из стандарта поддерживается на уровне planner-а.
• Системные представления sys.* — sys.queries, sys.column_stats, sys.health.

Системный каталог и метаданные

AngaraBase хранит метаданные всех объектов базы данных в центральном реестре — SysCatalog. Для пользователей доступ к метаданным предоставляется через системные представления sys.* и функции интроспекции.

Иерархия объектов

Объекты базы данных организованы в строгую иерархию:

Instance → Database → Schema → Table → Column

Каждый уровень имеет уникальный идентификатор в SysCatalog. Таблицы принадлежат схемам, схемы — базам данных, базы данных — экземпляру (instance).

SysCatalog

SysCatalog — центральный реестр метаданных. Он хранит информацию о:

• таблицах, колонках и их типах данных
• индексах и ограничениях (constraints)
• пользователях, ролях и привилегиях
• функциях и агрегатах
• политиках безопасности (RLS)
• статистике для оптимизатора запросов

SysCatalog обновляется при DDL-операциях (CREATE, ALTER, DROP) и при сборе статистики.

Системные представления (sys.*)

Системные представления доступны только для чтения и не требуют специальных привилегий (за исключением представлений, связанных с безопасностью).

Идентификация и состояние экземпляра

Структура данных

Статистика

Безопасность и доступ

Функции интроспекции

AngaraBase предоставляет набор встроенных функций для программного доступа к метаданным.

Роли и привилегии

Безопасность (RLS, audit, break-glass)

Диагностика и производительность

Практические примеры

Информация об экземпляре

SELECT * FROM sys.identity;

Проверка состояния сервера

SELECT * FROM sys.health;

Список всех таблиц

SELECT * FROM sys.tables;

Проверка настроек безопасности

SELECT name, value FROM sys.settings WHERE name LIKE 'security.%';

Просмотр статистики по колонкам таблицы

SELECT column_name, ndv_approx, null_count
FROM sys.column_stats
WHERE table_name = 'orders';

Проверка привилегий текущего пользователя

SELECT * FROM sys.my_privileges;
SELECT angara_has_privilege('orders', 'SELECT');

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

• Quickstart (примеры sys.*) — первые шаги с системными представлениями
• Безопасность — функции интроспекции безопасности
• Диагностика — мониторинг и устранение проблем
• Обработка запросов — как оптимизатор использует метаданные каталога

Instance Lifecycle

This document explains the conceptual model of AngaraBase instance identity, lifecycle, and the Instance Lease system that enables safe crash recovery and storage portability.

Instance Identity

Each AngaraBase instance has a unique identity established during initialization:

Core Identity Components

• cluster_id: UUID identifying the logical database cluster
• instance_id: UUID identifying this specific instance
• Data directory: Physical location of database files
• Transaction log directory: Physical location of WAL files

Identity Persistence

Identity is stored in two places:

1. VERSION marker: Binary file with format version and IDs
2. System catalog pages: In base.adb reserved pages with full metadata

Instance Lease System

The Instance Lease prevents multiple instances from accessing the same data files simultaneously, which would cause corruption.

Lease Structure

#![allow(unused)]
fn main() {
pub struct InstanceLeaseV0 {
 pub holder_id: String, // UUID of owning instance
 pub acquired_at_unix_s: u64, // When lease was taken
 pub expires_at_unix_s: u64, // When lease expires (TTL)
 pub holder_pid: u32, // Process ID (diagnostic)
 pub holder_hostname: String, // Hostname (diagnostic)
}
}

Lease State Machine

 [None] ──acquire──> [Held] ──heartbeat──> [Held]
 ↑ │ │
 │ │ │
 └──expired/release──┘ │
 │
 [Expired] <──────────timeout─────────────────┘
 │
 └──takeover──> [Held by new instance]

State Transitions

1. None → Held: First instance startup or after graceful shutdown
2. Held → Held: Periodic heartbeat updates (every 10s by default)
3. Held → None: Graceful shutdown releases lease immediately
4. Held → Expired: Heartbeat stops (crash, network partition)
5. Expired → Held: New instance takes over after TTL expiration

Lease Storage

• Location: Stored in SysCatalogMetaV0 within base.adb pages
• Persistence: Atomic updates with full page images
• Reliability: Works on NFS/SAN where flock() is unreliable

Startup Sequence

Phase 1: Pre-flight Checks

1. Verify data directory exists and is initialized
2. Check VERSION marker compatibility
3. Validate page size matches compiled binary

Phase 2: Lease Acquisition

1. Load system catalog from base.adb
2. Check existing lease status:

• No lease: Acquire immediately
• Expired lease: Take over with warning
• Active lease: Fail with informative error
• Force takeover: Override active lease (dangerous)

Phase 3: Recovery

1. WAL Recovery: Replay transaction log (file_bin backend)
2. MVCC Recovery: Restore in-memory transaction state
3. Heartbeat Start: Begin periodic lease renewal

Phase 4: Ready for Connections

1. Start protocol listeners (pgwire, admin)
2. Begin accepting client connections
3. Continue heartbeat until shutdown

Recovery Modes

AngaraBase tracks the recovery mode for operational visibility:

Normal Startup

• Clean start on existing, properly shut down data
• No WAL replay required
• recovery_mode = "normal"

Crash Recovery

• Previous instance terminated unexpectedly
• WAL replay recovers committed transactions
• MVCC state rebuilt from transaction log
• recovery_mode = "crash_recovery"

Forced Takeover

• Operator used ANGARABASE_FORCE_LEASE_TAKEOVER=1
• May indicate emergency recovery scenario
• recovery_mode = "forced_takeover"

Shared Storage Scenarios

The Instance Lease system enables AngaraBase to work correctly on shared storage where multiple hosts can access the same files.

NFS/SAN Deployment

Host A ──┐
 ├── NFS/SAN ──> [data/] [txlog/]
Host B ──┘ [base.adb with lease]

Benefits

• Failover: Host B can take over if Host A crashes
• Maintenance: Move instance between hosts without dump/restore
• Testing: Run against production data copies safely

Limitations

• Single writer: Only one instance can write at a time
• Network partitions: May cause false lease expiration
• Performance: Network storage latency affects throughput

File Copy Scenarios

For non-shared storage, manual file copy enables:

• Backup testing: Verify backup integrity on different host
• Development: Use production data copy for debugging
• Migration: Move to new hardware without downtime

Configuration

Lease Timing

• ANGARABASE_LEASE_TTL_S: How long lease lasts (default: 30s)
• ANGARABASE_LEASE_HEARTBEAT_S: Renewal frequency (default: 10s)

Safety Controls

• ANGARABASE_FORCE_LEASE_TAKEOVER: Emergency override (default: false)

Recommended Settings

# Production: Longer TTL for network stability
export ANGARABASE_LEASE_TTL_S=60
export ANGARABASE_LEASE_HEARTBEAT_S=20

# Development: Shorter TTL for faster iteration 
export ANGARABASE_LEASE_TTL_S=15
export ANGARABASE_LEASE_HEARTBEAT_S=5

Monitoring and Observability

Instance Status

-- Check current lease holder
SELECT lease_holder_id, lease_holder_hostname, 
 lease_expires_at, recovery_mode 
FROM sys.identity;

-- Check system health
SELECT uptime_seconds, txn_commit_epoch_current 
FROM sys.health;

Lease Events

AngaraBase logs lease events to stderr:

Instance lease acquired: holder=abc123...
Instance lease taken over: holder=def456...
Warning: lease heartbeat failed: I/O error
Instance lease released: holder=abc123...

Metrics Integration

Future versions will expose lease metrics via:

• Prometheus metrics endpoint
• sys.metrics virtual table
• Structured logging output

Security Considerations

Access Control

• Lease system does NOT provide authentication
• File system permissions still required
• Network access controls recommended for shared storage

Audit Trail

• Lease changes logged with timestamps
• Instance identity tracked in sys.identity
• Recovery mode visible for forensics

Troubleshooting

Common Issues

“Cannot start: database files are owned by another instance”

• Diagnosis: Active lease prevents startup
• Resolution: Wait for expiration or verify other instance is dead

Frequent lease takeovers

• Diagnosis: Network instability or resource contention
• Resolution: Increase TTL, check network/disk performance

“MVCC recovery failed”

• Diagnosis: Corrupted transaction log
• Resolution: Check filesystem, restore from backup if needed

Debug Information

-- Instance identity and lease
SELECT * FROM sys.identity;

-- Recent recovery statistics 
SELECT * FROM sys.health;

-- Transaction log status
SELECT * FROM sys.settings WHERE name LIKE 'transaction_log.%';

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

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

• Хранение данных — datadir, который защищает instance lease.
• Транзакции и MVCC — что происходит с активными транзакциями при forced_takeover.

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

• Crash recovery — операционные процедуры восстановления после аварийного завершения.
• Конфигурация — переменные instance_lease.*, recovery.*.
• Резервное копирование и восстановление — как защитить datadir и снять снапшот.

Справочник

• Системные представления sys.* — sys.identity, sys.health для диагностики lease-стейта.
• Известные ограничения и SQLSTATE — раздел INSTANCE_* ошибок.

SQL compatibility overview

Goal

Понять модель совместимости AngaraBase с PostgreSQL и быстро интерпретировать ошибки при тестировании.

Approach

AngaraBase реализует ограниченное подмножество PostgreSQL SQL через pgwire-протокол. Неподдерживаемые конструкции возвращают явный SQLSTATE (чаще всего 0A000 feature_not_supported), а не молчаливый некорректный результат.

Принцип: fail-closed — если feature не реализован, клиент получает детерминированную ошибку.

Source of truth

Practical advice

• ORM/tooling (DBeaver, psql, Hibernate и др.) часто выполняют pg_catalog запросы при подключении. Ориентируйтесь на результаты compat suite режимов --dbeaver-smoke / --nightly.
• Если вы наблюдаете hang/stall — это P0/P1 bug. Соберите артефакты по инструкции в Support.

SQLSTATE quick reference

Полный список с контекстом: Known issues.

SQL reference pages

Текущий статус подсистем SQL на ветке 0.6.x. Бэйджи отражают, насколько подсистема покрыта pinned-тестами compat-suite и можно ли на неё опираться в production-сценариях.

SQL Functions (RM-0.6.5.5)

AngaraBase implements a subset of PostgreSQL built-in functions.

Vector execution visibility

When vector execution mode allows vector path (ANGARABASE_SQL_EXECUTION_MODE=auto for supported plans, or force_vector), EXPLAIN surfaces vector operator names:

• VectorSeqScan
• VectorFilter
• VectorProject
• VectorHashJoin
• VectorAgg

If the plan shape is not supported by AngaraVector, planner/executor keeps row operators in EXPLAIN.

Execution mode behavior:

• auto (default) — Stable use vector only for fully supported plan shapes, otherwise deterministic row fallback.
• force_row — Stable always use row executor.
• force_vector — Experimental fail-closed with feature_not_supported if vector execution is not possible. Подходит для целевого тестирования векторного пути; не рекомендуется для production-нагрузки в 0.6.x.

AngaraMemory table options

CREATE TABLE ... WITH (...) now supports bounded memory-table surfaces:

• storage='memory' — Baseline selects AngaraMemory table engine.
• durability='none'|'logged'|'snapshotted' — Baseline volatile/durable behavior.
• max_rows=<n> — Stable hard row-cap; overflow is fail-closed (54023).
• eviction_policy='error'|'fifo' — Experimental default error; fifo is opt-in.
• checkpoint_interval_ms=<n> — Baseline valid only with durability='snapshotted'.

If max_rows is omitted for memory tables, bounded default is applied from instance policy.

Behavior clarification for durability='snapshotted':

• DML hot path does not perform immediate page persistence.
• Checkpoint worker applies per-table scheduling using each table’s checkpoint_interval_ms (with bounded fallback).

Links

• Known issues: Known issues
• Support: Support
• Security model: Security / authorization

Data types

Goal

Справочник поддерживаемых типов данных AngaraBase и правила приведения типов.

Supported types

Text-backed temporal types

TIMESTAMP и DATE хранятся в text-backed compatibility mode. Это означает:

• Сравнения выполняются как текстовые (лексикографические); ISO 8601 формат гарантирует корректный порядок.
• Serialization (RM-0.6.5.5): TIMESTAMP всегда сериализуется в UTC без смещения (например, 2026-05-07 14:30:00.123). Трейлинг-нули микросекунд обрезаются.
• Арифметика (INTERVAL и пр.) не поддерживается — 0A000.
• BRIN-индексы на date / timestamp / timestamptz колонках поддерживаются (используют текстовые min/max).

Planned types

Попытка использовать неподдерживаемый тип приведёт к ошибке парсера или 0A000 feature_not_supported.

NULL handling

• Все типы допускают NULL, если колонка не объявлена как NOT NULL.
• В ORDER BY ASC значения NULL трактуются как наибольшие (выводятся последними).
• Явное управление NULLS FIRST / NULLS LAST не поддерживается — 0A000.

Type casting

AngaraBase поддерживает PostgreSQL-синтаксис приведения типов:

SELECT '42'::INTEGER;
SELECT id::TEXT FROM t;

Приведение между несовместимыми типами приводит к runtime-ошибке с соответствующим SQLSTATE.

Expected SQLSTATE

Links

• SQL compatibility overview: overview.md
• DDL (CREATE TABLE с типами): ddl.md
• Known issues: Known issues

DDL — Data Definition Language

Goal

Справочник поддерживаемых DDL-операций: создание, изменение и удаление таблиц, индексов и ограничений.

CREATE TABLE

Basic form

CREATE TABLE t (
 id INTEGER PRIMARY KEY,
 name VARCHAR(100) NOT NULL,
 v BIGINT
);

With table options

CREATE TABLE events (
 id INTEGER PRIMARY KEY,
 ts TIMESTAMP NOT NULL,
 data TEXT
) WITH (append_only = true);

CREATE TABLE ledger (
 id INTEGER PRIMARY KEY,
 amount BIGINT,
 ref_id INTEGER
) WITH (mutation_policy = 'no_delete');

Constraints

• PRIMARY KEY — обязателен для каждой таблицы (ровно один).
• NOT NULL — колонка не принимает NULL.
• FOREIGN KEY ... NOT ENFORCED — декларативный FK без runtime-проверки.

CREATE TABLE orders (
 id INTEGER PRIMARY KEY,
 parent_id INTEGER NOT NULL,
 FOREIGN KEY (parent_id) REFERENCES parents (id) NOT ENFORCED
);

Enforced foreign keys не поддерживаются — попытка создать FK без NOT ENFORCED вернёт 0A000.

ALTER TABLE

Table-level options

ALTER TABLE t SET (append_only = true);
ALTER TABLE t SET (append_only = false);
ALTER TABLE t SET (mutation_policy = 'no_delete');
ALTER TABLE t SET (mutation_policy = 'unrestricted');

ALTER TABLE t SET (stats_level_max = 2);
ALTER TABLE t SET (stats_reservoir_size = 1000);

Column-level options

ALTER TABLE t ALTER COLUMN v SET (stats_level_max = 1);

Table options reference

append_only = true эквивалентен mutation_policy = 'append_only'.

DROP TABLE

DROP TABLE t;

При DROP TABLE каскадно удаляются связанные owned-последовательности (SERIAL/IDENTITY), даже без CASCADE (поведение PostgreSQL).

CREATE / ALTER / DROP SEQUENCE

AngaraBase поддерживает first-class объекты-последовательности (SEQUENCE) — RM-0.6.3.7, RFC-2026-497. Они сохраняются в sys_catalog, переживают рестарт сервера и обслуживают SERIAL/BIGSERIAL и GENERATED [ALWAYS|BY DEFAULT] AS IDENTITY.

CREATE SEQUENCE

CREATE SEQUENCE s1;                                                -- start=1, inc=1, без верхней границы
CREATE SEQUENCE s2 START WITH 100 INCREMENT BY 5;
CREATE SEQUENCE s3 MINVALUE 1 MAXVALUE 999 CYCLE;                  -- циклический счётчик
CREATE SEQUENCE IF NOT EXISTS s1;                                  -- идемпотентно

Опции (порядок свободный): START WITH n, INCREMENT BY n, MINVALUE n / NO MINVALUE, MAXVALUE n / NO MAXVALUE, CYCLE / NO CYCLE.

ALTER SEQUENCE

ALTER SEQUENCE s1 INCREMENT BY 10;
ALTER SEQUENCE s1 RESTART WITH 1;                                  -- сбросить счётчик
ALTER SEQUENCE s1 MAXVALUE 1000 NO CYCLE;
ALTER SEQUENCE t_id_seq OWNED BY t.id;                             -- привязка к колонке
ALTER SEQUENCE s1 OWNED BY NONE;                                   -- отвязать

DROP SEQUENCE

DROP SEQUENCE s1;
DROP SEQUENCE IF EXISTS s1;
DROP SEQUENCE s1 CASCADE;

Поведение функций

См. dml.md — раздел «Sequence functions» (nextval, currval, setval).

SQLSTATE

CREATE INDEX

AngaraBase поддерживает одноколоночные индексы двух типов: btree (default) и brin.

-- btree (default)
CREATE INDEX idx_t_v ON t (v);

-- btree (explicit)
CREATE INDEX idx_t_v ON t USING btree (v);

-- brin
CREATE INDEX idx_events_ts ON events USING brin (ts);

BRIN supported key types

BRIN остаётся accelerator path с heap fetch + MVCC predicate recheck.

Current bounds

• Только одноколоночные индексы.
• Составные и выражения-индексы не поддерживаются — 0A000.
• Unsupported index methods (GIN, GiST и др.) — 0A000.

Expected SQLSTATE

Links

• Data types: data-types.md
• DML (INSERT/UPDATE/DELETE): dml.md
• Partitioning (CREATE TABLE … PARTITION BY): partitioning.md
• Known issues: Known issues

DML — Data Manipulation Language

Goal

Справочник поддерживаемых DML-операций и поведение mutation policy.

INSERT

INSERT INTO t (id, v) VALUES (1, 100);
INSERT INTO t (id, v) VALUES (2, 200), (3, 300);

Для секционированных таблиц INSERT в родительскую таблицу автоматически маршрутизирует строку в подходящую партицию. Если подходящая партиция (и DEFAULT) отсутствует — 23514 check_violation.

INSERT … SELECT

RM-0.6.3.7 (RFC-2026-497, S8): источник INSERT — произвольный SELECT-запрос. Колонки результата сопоставляются с целевыми по позиции (или по явному списку колонок); SERIAL/IDENTITY/DEFAULT резолвятся для каждой строки независимо.

INSERT INTO archive (id, v) SELECT id, v FROM t WHERE created_at < '2025-01-01';
INSERT INTO log (note) SELECT 'rebuilt:' || name FROM rebuilt_items;

INSERT … ON CONFLICT (UPSERT)

RM-0.6.3.7 (RFC-2026-497, S9): поддерживается одно-колоночный конфликтный target (или PK по умолчанию). EXCLUDED.<col> ссылается на предложенную строку.

-- DO NOTHING (раннее поведение, теперь принимает явный target):
INSERT INTO t (id, v) VALUES (1, 100) ON CONFLICT (id) DO NOTHING;

-- DO UPDATE SET ... [WHERE ...]
INSERT INTO counters (key, n)
VALUES ('hits', 1)
ON CONFLICT (key) DO UPDATE SET n = counters.n + EXCLUDED.n;

-- WHERE-фильтр над существующей строкой (PG-семантика: конфликт + WHERE-false = silent no-op):
INSERT INTO inventory (sku, qty)
VALUES ('A', 5)
ON CONFLICT (sku) DO UPDATE SET qty = EXCLUDED.qty
WHERE inventory.qty < EXCLUDED.qty;

Не поддерживается:

• мультиколоночный target (ON CONFLICT (a, b)) → 0A000;
• ON CONFLICT ON CONSTRAINT <name> → 0A000.

UPDATE

UPDATE t SET v = 999 WHERE id = 1;

Начиная с RM-0.6.5.5, UPDATE SET поддерживает функциональные выражения и приведение типов:

• UPDATE t SET write_date = NOW() WHERE id = 1;
• UPDATE t SET ts = '2026-05-07 14:30:00'::timestamp WHERE id = 1;
• UPDATE t SET day = date_trunc('day', NOW()) WHERE id = 1;

Поддерживаются NOW(), CURRENT_TIMESTAMP, CURRENT_DATE, date_trunc() и явные CAST (синтаксис ::).

DELETE

DELETE FROM t WHERE id = 2;

RETURNING

RM-0.6.3.7 (RFC-2026-497, S10): RETURNING поддержан для multi-row INSERT, UPDATE, DELETE. В проекции допустимы *, явный список колонок и выражения. Для INSERT ... ON CONFLICT DO UPDATE возвращается пост-апдейт строка (как в PostgreSQL).

INSERT INTO t (v) VALUES (100), (200), (300) RETURNING id, v;
UPDATE t SET v = v + 1 WHERE v > 0 RETURNING id, v AS new_v;
DELETE FROM t WHERE v IS NULL RETURNING id;

Sequence functions

RM-0.6.3.7 (RFC-2026-497): nextval / currval / setval для объектов SEQUENCE (см. ddl.md — раздел «CREATE / ALTER / DROP SEQUENCE»). Не транзакционные: gap-on-rollback корректное поведение.

SELECT nextval('s1');                  -- 1, 2, 3, ...; overflow без CYCLE → 2200H
SELECT currval('s1');                  -- последнее значение, выданное в ЭТОЙ сессии
SELECT setval('s1', 100);              -- last_value=100, is_called=true; следующий nextval = 101
SELECT setval('s1', 50, false);        -- следующий nextval = 50

currval — session-bound: возвращает значение последнего nextval (или setval(_, _, true)) в той же pgwire-сессии. Если в текущей сессии nextval ещё не вызывался — 55000 object_not_in_prerequisite_state, независимо от того, что nextval был вызван в других сессиях.

SERIAL / IDENTITY

SERIAL / BIGSERIAL и GENERATED [ALWAYS|BY DEFAULT] AS IDENTITY автоматически создают owned-последовательность <table>_<col>_seq, которая удаляется вместе с таблицей.

CREATE TABLE users (id SERIAL PRIMARY KEY, name TEXT);
INSERT INTO users (name) VALUES ('alice'), ('bob') RETURNING id;
-- id заполняется через nextval('users_id_seq')

CREATE TABLE orders (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  amount NUMERIC
);
INSERT INTO orders (id, amount) VALUES (42, 100);
-- → 428C9 generated_always: id колонка GENERATED ALWAYS

CREATE TABLE invoices (
  id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  total NUMERIC
);
INSERT INTO invoices (id, total) VALUES (DEFAULT, 250) RETURNING id;
INSERT INTO invoices (id, total) VALUES (1000, 250);     -- explicit OK

SELECT

SELECT id, v FROM t WHERE v > 50 ORDER BY id;

Подробно о запросах (CTE, JOIN, GROUP BY и т.д.) — см. queries.md.

TRUNCATE

TRUNCATE TABLE t;

TRUNCATE — DDL-сброс таблицы. Для append-only таблиц это единственный способ удалить данные.

Mutation policy enforcement

Mutation policy контролирует допустимые DML-операции на таблице.

append_only

no_delete

unrestricted

Все DML-операции разрешены (поведение по умолчанию).

Autocommit vs explicit transactions

По умолчанию каждый DML-запрос выполняется в autocommit-режиме (неявная транзакция, фиксируется сразу).

Для явных транзакций:

BEGIN;
INSERT INTO t (id, v) VALUES (10, 1000);
UPDATE t SET v = 2000 WHERE id = 10;
COMMIT;

ROLLBACK откатывает все изменения текущей транзакции.

Expected SQLSTATE

Links

• DDL (CREATE TABLE, mutation policy options): ddl.md
• Queries (SELECT details): queries.md
• Partitioning: partitioning.md
• Known issues: Known issues

Queries

Goal

Справочник поддерживаемых форм запросов: CTE, JOIN, агрегация, сортировка, статистические поверхности.

Non-recursive WITH (CTE)

AngaraBase поддерживает ограниченные (non-recursive) CTE как derived source в FROM:

WITH recent AS (
 SELECT id, v FROM t WHERE v > 100
)
SELECT r.id, r.v
FROM recent r
ORDER BY r.id;

Supported CTE projection forms

WITH c AS (SELECT id, v FROM t)
SELECT * FROM c WHERE id < 10;

Explicitly unsupported

• WITH RECURSIVE — 0A000 feature_not_supported
• Data-modifying CTEs (WITH ... INSERT/UPDATE/DELETE) — 0A000 feature_not_supported

JOINs

SELECT a.id, b.name
FROM orders a
INNER JOIN customers b ON a.customer_id = b.id;

SELECT a.id, b.name
FROM orders a
LEFT JOIN customers b ON a.customer_id = b.id;

Поддерживаются: INNER JOIN, LEFT JOIN.

ORDER BY

SELECT * FROM t ORDER BY v;
SELECT * FROM t ORDER BY v ASC;
SELECT * FROM t ORDER BY v DESC;

ORDER BY <expr> поддерживает ограниченные скалярные выражения, уже поддерживаемые движком.

Поддержка псевдонимов (Aliases)

ORDER BY может ссылаться на псевдонимы (алиасы), определённые в SELECT-списке с помощью ключевого слова AS. Это работает как для обычных колонок, так и для результатов агрегации:

-- Алиас для выражения
SELECT x * 2 AS doubled FROM t ORDER BY doubled;

-- Алиас для агрегации
SELECT grp, sum(amount) AS total 
FROM t 
GROUP BY grp 
ORDER BY total DESC;

Порядковые номера колонок (Ordinals)

Поддерживается сортировка по порядковому номеру колонки в SELECT-списке (1-based), согласно стандарту SQL:2011:

-- Сортировка по первой колонке (a)
SELECT a, b FROM t ORDER BY 1;

-- Сортировка по второй колонке (b) в обратном порядке
SELECT a, b FROM t ORDER BY 2 DESC;

Если указанный номер выходит за пределы количества колонок в запросе (или равен 0), возвращается ошибка 42P10 (invalid_column_reference).

NULL ordering

• В ASC порядке NULL трактуется как наибольшее значение (выводится последним).
• В DESC порядке NULL выводится первым.
• Явное NULLS FIRST / NULLS LAST не поддерживается — 0A000.

GROUP BY / HAVING

SELECT v, COUNT(*) AS cnt
FROM t
GROUP BY v
HAVING COUNT(*) > 1;

LIMIT / OFFSET

SELECT * FROM t ORDER BY id LIMIT 10;
SELECT * FROM t ORDER BY id LIMIT 10 OFFSET 20;

Ошибки в выражениях (Expression Errors)

При использовании несовместимых типов в арифметических выражениях (например, попытка сложения строки с числом 'строка' + 1), AngaraBase возвращает ошибку 42883 (undefined_function / operator not found).

Примечание: строковые литералы, содержащие числа (например, '123'), могут автоматически приводиться к числовому типу в зависимости от контекста.

Unsupported query forms

AngaraStat surfaces

AngaraBase предоставляет встроенные статистические представления.

sys.table_stats

sys.column_stats

SELECT * FROM sys.table_stats WHERE table_name = 'events';
SELECT * FROM sys.column_stats WHERE table_name = 'events' AND column_name = 'ts';

Expected SQLSTATE

Links

• DML operations: dml.md
• DDL (stats options): ddl.md
• SQL compatibility overview: overview.md
• Known issues: Known issues

Table partitioning

Goal

Справочник секционирования таблиц: RANGE, LIST, управление партициями и runtime-поведение.

PARTITION BY RANGE

CREATE TABLE events (
 id INTEGER PRIMARY KEY,
 ts DATE NOT NULL,
 data TEXT
) PARTITION BY RANGE (ts);

Range partitions

CREATE TABLE events_2025 PARTITION OF events
 FOR VALUES FROM ('2025-01-01') TO ('2026-01-01');

CREATE TABLE events_2026 PARTITION OF events
 FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');

PARTITION BY LIST

CREATE TABLE metrics (
 id INTEGER PRIMARY KEY,
 region VARCHAR(20) NOT NULL,
 value BIGINT
) PARTITION BY LIST (region);

List partitions

CREATE TABLE metrics_eu PARTITION OF metrics
 FOR VALUES IN ('eu-west', 'eu-east');

CREATE TABLE metrics_us PARTITION OF metrics
 FOR VALUES IN ('us-east', 'us-west');

DEFAULT partition

CREATE TABLE events_other PARTITION OF events DEFAULT;

Строки, не подпадающие ни под одну партицию, попадают в DEFAULT. Если DEFAULT не существует и подходящая партиция не найдена — 23514 check_violation.

ALTER TABLE — attach / detach

ALTER TABLE events ATTACH PARTITION events_2027
 FOR VALUES FROM ('2027-01-01') TO ('2028-01-01');

ALTER TABLE events DETACH PARTITION events_2025;

DROP PARTITION

DROP PARTITION events_2025;

Runtime behavior

INSERT routing

INSERT в родительскую таблицу автоматически маршрутизирует строку в подходящую дочернюю партицию:

INSERT INTO events (id, ts, data) VALUES (1, '2026-06-15', 'test');
-- → events_2026

Если ни одна партиция не подходит и DEFAULT отсутствует:

ERROR: 23514: new row for relation "events" violates check constraint

Append-only inheritance

Если родительская таблица объявлена как append_only = true:

• Все присоединённые партиции наследуют режим append-only.
• Партиция не может отключить append_only пока родитель остаётся append-only — 42809.

CREATE TABLE events (
 id INTEGER PRIMARY KEY,
 ts DATE NOT NULL
) PARTITION BY RANGE (ts) WITH (append_only = true);

-- partitions inherit append_only
CREATE TABLE events_2026 PARTITION OF events
 FOR VALUES FROM ('2026-01-01') TO ('2027-01-01');

Current v0 bounds

Неподдерживаемые формы возвращают 0A000 feature_not_supported.

Expected SQLSTATE

Links

• DDL reference: ddl.md
• DML (INSERT routing): dml.md
• SQL compatibility overview: overview.md
• Known issues: Known issues

Security model (overview)

Goal

Understand the layered security architecture of AngaraBase: which controls exist, how they interact, and how to verify your instance is running in a secure configuration.

Prerequisites

• A running AngaraBase instance (local or staging).
• SQL session access (pgwire).
• Basic understanding of roles and tables in your database.

Security model (layers)

AngaraBase uses a layered defence model. Each layer is independent and composable — no single layer bypass compromises the whole.

Layer 1 — Transport and identity

• TLS protects the wire protocol.
• Auth modes (trust, scram, cert) control how clients prove identity.
• Fail-closed: remote bind without TLS is rejected when tls.require_on_remote_bind = true.

See authentication.md for setup and verification.

Layer 2 — Authorization and data visibility

• RBAC (roles, grants, privileges) decides whether an operation is allowed at all.
• RLS (row-level security policies) decides which rows are visible or modifiable.
• Deny-by-default: enabling RLS without policies blocks all rows, including for the table owner.

See authorization.md for SQL surface and introspection.

Layer 3 — Controlled privilege escalation

• Break-glass is the only way to bypass RLS — even SUPERUSER cannot.
• Activation requires a mandatory REASON and TTL.
• Every query during break-glass generates a dedicated audit entry.

See break-glass.md for the full lifecycle.

Layer 4 — Audit and accountability

• Audit chain is append-only and tamper-evident (SHA-256 chain hash).
• Scope: auth, DDL, DCL, policy changes, break-glass lifecycle.
• DML audit policy: configurable off|allowlist|denylist per table.

See audit.md for configuration and verification.

Layer 5 — Data-at-rest protection

• TDE (Transparent Data Encryption) covers pages, WAL, and audit sink.
• Fail-closed: missing or invalid key material prevents startup and audit I/O.

See encryption.md for TDE setup and key management.

Layer 6 — Client-encrypted columns (v0)

• Server stores ciphertext + metadata (alg, mode, key_id) but never the keys.
• DETERMINISTIC mode allows equality predicates; RANDOMIZED rejects server-side predicates (0A000).

See encryption.md for the SQL surface and operator rules.

How features work together

Quick security verification

Step 1 — Check effective settings

SELECT name, value
FROM sys.settings
WHERE name LIKE 'tls.%'
 OR name LIKE 'security.%'
 OR name LIKE 'audit.%'
ORDER BY name;

Returns effective security knobs without exposing secrets.

Step 2 — Check security surfaces

SELECT * FROM angara_user_roles() LIMIT 20;
SELECT * FROM angara_table_policies('public.users');
SELECT * FROM angara_break_glass_status();
SELECT * FROM angara_audit_verify_chain();

Validates that key introspection/verification functions are available and responsive.

Step 3 — Validate RLS explanation surface

SELECT * FROM angara_effective_rls_predicate('public.users');

Returns the effective predicate and helps explain row-visibility behaviour.

Expected result

• sys.settings shows security knobs without secrets.
• Security functions return data (or empty results) without internal errors.
• Unsupported operations terminate with an explicit SQLSTATE (0A000, 42501, or 22023) — never a silent bypass.

Troubleshooting

• 42501 insufficient_privilege on security DDL/ops Check user roles and session context; see authorization.md.
• 0A000 feature_not_supported in policy/encrypted path This is a bounded contract (not a bug) — use the supported syntax or mode.
• TDE enabled but audit/data I/O fails Verify master key presence and correctness; fail-closed is expected. See encryption.md.
• Need a bug-report artifact? Follow the bundle steps in ../reference/support.md.

Links

• Security knobs registry: angarabook/src/operations/security-operations.md

• Authentication: authentication.md

• Authorization: authorization.md

• Audit: audit.md

• Encryption: encryption.md

• Break-glass: break-glass.md

• Hardening runbook: hardening.md

Authentication

Goal

Configure and verify transport security (TLS) and client authentication modes so that only identified clients can connect to AngaraBase.

Prerequisites

• Access to the server configuration (TOML config and/or environment variables).
• TLS certificate and key files (for scram or cert modes with remote clients).
• Ability to restart the server after configuration changes.

Auth modes

AngaraBase supports three authentication modes, set via ANGARABASE_AUTH_MODE or security.auth_mode in the config:

Default: trust (requires explicit opt-in flag for remote bind — see Startup safety below).

Steps

1) Configure TLS

TLS is controlled in the [tls] section of angarabase.conf:

[tls]
enabled = true
cert_path = "/etc/angarabase/tls/server.crt"
key_path = "/etc/angarabase/tls/server.key"
require_on_remote_bind = true

Or via environment variables:

export ANGARABASE_TLS_ENABLED=1
export ANGARABASE_TLS_CERT_PATH=/etc/angarabase/tls/server.crt
export ANGARABASE_TLS_KEY_PATH=/etc/angarabase/tls/server.key
export ANGARABASE_TLS_REQUIRE_ON_REMOTE_BIND=1

require_on_remote_bind = true enforces fail-closed behaviour: if the server binds to a non-loopback address and TLS is not enabled, startup is refused.

2) Set auth mode

export ANGARABASE_AUTH_MODE=scram

Or in angarabase.conf:

[security]
auth_mode = "scram"

3) SCRAM setup

When auth_mode = scram, the superuser must be bootstrapped with a password at init time:

angarabase-server --init /var/lib/angarabase \
 --superuser admin \
 --superuser-password 'strong-password' \
 --auth-mode scram

The password is converted to a SCRAM-SHA-256 verifier before it touches disk — plaintext is never stored.

Additional users are created via SQL:

CREATE USER app_reader WITH PASSWORD 'change-me';

Password storage format: SCRAM-SHA-256$<iterations>:<salt>$<StoredKey>:<ServerKey>.

4) Startup safety

To protect against accidental production use of trust mode:

• trust mode on a non-loopback bind address requires the explicit flag --allow-insecure-no-auth.
• Without this flag the server refuses to start (fail-closed).
• scram or cert modes do not require the flag.

5) Verify effective config from SQL

After startup, confirm the active settings:

SELECT name, value
FROM sys.settings
WHERE name IN (
 'tls.enabled',
 'tls.require_on_remote_bind',
 'security.auth_mode'
)
ORDER BY name;

No secret material (keys, passwords, verifiers) appears in sys.settings.

Expected result

• In scram mode, unauthenticated connections are rejected.
• In cert mode, clients without a valid certificate are rejected.
• trust on remote bind without --allow-insecure-no-auth prevents startup.
• sys.settings confirms the effective auth mode and TLS state without leaking secrets.

Troubleshooting

• Server refuses to start in trust mode You are binding to a non-loopback address. Either switch to scram/cert or pass --allow-insecure-no-auth for development.
• authentication failed for user "..." on connect Verify the password or certificate; check that security.auth_mode matches the client’s auth method.
• TLS handshake failure Confirm cert_path and key_path point to valid, non-expired files; verify the client’s sslmode setting.
• Init refused: scram requires password Provide --superuser-password (or --superuser-password-file) when --auth-mode scram is set.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Hardening runbook: hardening.md
• Configuration reference: ../operations/configuration.md
• Security knobs registry: angarabook/src/operations/security-operations.md

Authorization (RBAC and RLS)

Goal

Set up role-based access control and row-level security policies so that users see and modify only the data they are permitted to.

Prerequisites

• SQL session with a user that has SUPERUSER or SECURITY_ADMIN privileges.
• A test table (e.g. public.users) with representative data.

RBAC — users, roles, privileges

Create a user and grant a role

CREATE USER app_reader WITH PASSWORD 'change-me';
GRANT reader TO app_reader;
GRANT SELECT ON public.users TO reader;

Object-level grants

GRANT SELECT ON TABLE public.orders TO analyst;
GRANT INSERT, UPDATE ON TABLE public.orders TO writer_role;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO analyst;

Default policy is deny-by-default: a user without an explicit GRANT cannot access another user’s tables.

Built-in role hierarchy

SUPERUSER
├── SECURITY_ADMIN — policy, audit, key, and break-glass management
├── DBA — ops (shutdown, backup, restore, settings, diagnostics)
├── CREATEROLE — CREATE/ALTER/DROP USER and ROLE
└── CREATEDB — CREATE DATABASE

SUPERUSER does not bypass RLS — only BREAK_GLASS can (see break-glass.md).

RLS — row-level security

Enable RLS on a table

ALTER TABLE public.users ENABLE ROW LEVEL SECURITY;

After this, the table follows deny-by-default: no rows are visible to anyone (including the owner) until at least one policy is created.

Create a security policy

CREATE SECURITY POLICY p_users_tenant ON public.users
 USING (tenant_id = current_setting('app.tenant_id')::int);

The USING predicate is injected as an automatic WHERE clause on SELECT, INSERT, UPDATE, and DELETE.

RLS enforcement rules

Multiple policies on one table use AND semantics — all must pass.

RLS v1 masking metadata

Policies can include a MASK clause for user-facing field masking:

ALTER SECURITY POLICY p_users_tenant ON public.users
 USING (tenant_id = current_setting('app.tenant_id')::int)
 MASK (email USING 'partial');

Supported mask types in v1:

Unsupported mask expressions return 0A000 feature_not_supported.

Unsupported predicates — fail-closed

In the IR/planner mode, complex predicates that cannot be safely rewritten (subqueries, arbitrary function calls, JOINs) are rejected:

ERROR: 0A000 feature_not_supported
 unsupported RLS predicate form

This is a bounded contract, not a bug. Use the supported predicate language (column references, current_setting(), current_user, literals, comparisons, AND/OR/NOT, IN, IS [NOT] NULL, type casts).

Introspection

SELECT * FROM angara_table_policies('public.users');
SELECT * FROM angara_effective_rls_predicate('public.users');
SELECT * FROM sys.users;
SELECT * FROM sys.roles;
SELECT * FROM sys.user_roles;
SELECT * FROM sys.role_privileges;
SELECT * FROM sys.object_grants;
SELECT * FROM sys.my_privileges;
SELECT * FROM sys.security_policies;
SELECT * FROM angara_user_roles('alice');
SELECT * FROM angara_user_privileges('alice');
SELECT angara_has_privilege('alice', 'SELECT', 'TABLE', 'public.orders');
SELECT angara_is_rls_active('public.users');

angara_effective_rls_predicate() shows the combined predicate, provenance, and mask metadata for a table — useful for explaining row-visibility behaviour.

Expected result

• RBAC grants control object-level access; users without grants are denied.
• RLS predicates filter rows transparently on SELECT/INSERT/UPDATE/DELETE.
• angara_table_policies reflects active policies, mask metadata, and provenance.
• Unsupported paths return a deterministic SQLSTATE, never a silent bypass.

Troubleshooting

• 42501 insufficient_privilege The current user lacks the required role or grant. Check sys.my_privileges and angara_user_roles().
• 0A000 feature_not_supported on RLS policy or mask The predicate or mask expression is outside the supported v1 syntax. Simplify the expression.
• Rows unexpectedly invisible after enabling RLS Deny-by-default is working correctly. Create a SECURITY POLICY with a USING predicate to allow the intended rows.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Break-glass (RLS bypass): break-glass.md
• Audit: audit.md
• SQL compatibility: ../sql-reference/overview.md
• Known issues: ../reference/known-issues.md

Audit

Goal

Understand and configure AngaraBase’s tamper-evident audit subsystem: chain verification, DML audit policy, and JSON export.

Prerequisites

• A running AngaraBase instance with audit enabled (default).
• SQL session with SECURITY_ADMIN or SUPERUSER privileges (for configuration changes).
• Write-accessible path for the audit log file.

Audit chain concept

AngaraBase maintains an append-only, tamper-evident audit trail:

• Every security-relevant event (auth, DDL, DCL, policy changes, break-glass lifecycle) produces an AuditEvent.
• Each event contains prev_hash — a SHA-256 hash of the preceding entry, forming a hash chain.
• Breaking or modifying any entry invalidates all subsequent hashes, making tampering detectable.
• The chain is separate from the transactional data path — audit events are recorded even for rolled-back transactions.

Audit scope

Steps

1) Verify chain integrity

SELECT * FROM angara_audit_verify_chain();

Returns is_valid, first_broken_seq, and details. A healthy chain returns is_valid = true.

2) Query the audit log

SELECT * FROM sys.audit_log
WHERE event_type = 'break_glass_query'
 AND timestamp > now() - INTERVAL '24 hours'
ORDER BY seq DESC
LIMIT 50;

Columns: seq, timestamp, event_type, user_name, auth_method, client_ip, database, session_claims, payload, prev_hash.

3) Configure audit v1 DML policy

DML audit is controlled by three knobs:

export ANGARABASE_AUDIT_DML_MODE=allowlist
export ANGARABASE_AUDIT_DML_ALLOWLIST=public.users,public.payments

Use ANGARABASE_AUDIT_DML_DENYLIST for the denylist.

Malformed policy or ambiguous object references cause a startup/config-apply rejection (fail-closed).

4) Configure audit log path

export ANGARABASE_AUDIT_LOG_PATH=/var/lib/angarabase/audit/audit.jsonl

The path must be writable. If the path is inaccessible, audit writes fail-closed.

5) Configure JSON export

export ANGARABASE_AUDIT_EXPORT_JSON_ENABLED=1
export ANGARABASE_AUDIT_EXPORT_RATE_LIMIT_RPS=50

Export is bounded and rate-limited. Export failures are reported but never expose secret payload fragments in error text.

6) TDE interaction

When TDE is enabled (ANGARABASE_TDE_ENABLE=1), the audit sink on disk is encrypted transparently:

• Key: audit_dek = KDF(master_key, domain="audit-v0", key_id).
• sys.audit_log decrypts on read when the correct key is available.
• Without the key, audit read/write is impossible (fail-closed).
• Encrypted audit data remains encrypted in backups and copied artefacts.

See encryption.md for TDE configuration.

Expected result

• angara_audit_verify_chain() returns is_valid = true for an intact chain.
• sys.audit_log shows auth, DDL, DCL, policy, and break-glass events.
• With DML policy set to allowlist or denylist, matching DML operations appear in the audit log.
• TDE-encrypted audit files are unreadable without the master key.

Troubleshooting

• angara_audit_verify_chain() returns is_valid = false The chain has been tampered with or corrupted. Note the first_broken_seq and investigate the audit file. The audit subsystem can self-repair by truncating to the last valid entry.
• DML events not appearing in audit log Check audit.dml_mode — default is off. Verify that the target table is in the allowlist (or not in the denylist).
• Audit write failures after enabling TDE Verify ANGARABASE_TDE_MASTER_KEY_HEX and key validity. Fail-closed behaviour is expected when key material is missing.
• Break-glass activation fails with “audit subsystem unavailable” Break-glass requires a healthy audit subsystem. Fix the audit path or key material first.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Encryption (TDE): encryption.md
• Break-glass: break-glass.md
• Configuration reference: ../operations/configuration.md

Encryption

Goal

Configure data-at-rest protection with TDE and understand the server-side contract for client-encrypted columns.

Prerequisites

• Access to server environment variables or configuration file.
• A 256-bit master key (64 hex characters) for TDE.
• Ability to restart the server after TDE changes.

TDE — Transparent Data Encryption (v0)

TDE encrypts data at rest without application changes. When enabled, the following are encrypted:

• Storage pages (the .adb data file).
• WAL (write-ahead log) entries.
• Audit sink on disk (JSONL trail).

Configure TDE

export ANGARABASE_TDE_ENABLE=1
export ANGARABASE_TDE_MASTER_KEY_HEX=<64-hex-characters>
export ANGARABASE_TDE_MASTER_KEY_ID=master-prod-2026q1
export ANGARABASE_TDE_LAST_ROTATION_UNIX=1760000000

Fail-closed behaviour

• If ANGARABASE_TDE_ENABLE=1 and the key is missing, malformed, or wrong length, the server refuses to start.
• If the key is invalid for the existing data directory, page/WAL decryption fails at startup — also fail-closed.
• The audit sink follows the same rule: without a valid key, audit read/write is impossible.

Verify from SQL

SELECT name, value
FROM sys.settings
WHERE name IN (
 'security.tde_enabled',
 'security.tde_master_key_id'
)
ORDER BY name;

Only non-secret metadata (key_id, enabled flag) is exposed. The hex key itself never appears.

Client-encrypted columns

Client-encrypted columns allow applications to store ciphertext in the database while the server never holds key material.

SQL surface

ALTER TABLE customers
 ALTER COLUMN tax_id
 SET ENCRYPTED WITH (TYPE=DETERMINISTIC, KEY_ID='cust-key-01');

Full syntax:

ALTER TABLE <table>
 ALTER COLUMN <column>
 SET ENCRYPTED WITH (
 TYPE = DETERMINISTIC | RANDOMIZED,
 KEY_ID = '<opaque-id>',
 ALG = '<algorithm-id>' -- optional, defaults to AES-256-SIV / AES-256-GCM
 );

What the server stores

The server never accepts raw key material via SQL, environment variables, config, logs, or sys.* views.

Operator rules

Unsupported operations return 0A000 feature_not_supported (shape-stable error).

Fail-closed and observability

• Missing or invalid encryption metadata on a column causes DML to be rejected.
• sys.settings and diagnostics expose only key_id, mode, and algorithm — never ciphertext blobs or key-like material.
• Error messages never include ciphertext fragments or key material.

Expected result

• With TDE enabled, the data directory contains no plaintext data, WAL, or audit payloads.
• sys.settings shows security.tde_enabled = true and the key_id without exposing the key.
• Client-encrypted columns store ciphertext; deterministic mode allows equality queries; randomized mode rejects server-side predicates.
• All fail-closed paths produce deterministic errors, not silent fallbacks.

Troubleshooting

• Server refuses to start after enabling TDE Check ANGARABASE_TDE_MASTER_KEY_HEX — must be exactly 64 hex characters. If the data directory was previously unencrypted, you cannot enable TDE retroactively on existing data (see migration docs).
• 0A000 feature_not_supported on encrypted column query The query uses an unsupported operator for the column’s encryption mode. For RANDOMIZED columns, only read/write is allowed. For DETERMINISTIC, only equality predicates work.
• Audit read/write fails with TDE enabled The audit DEK derives from the master key. Verify the master key matches the one used when the audit file was created.
• sys.settings does not show TDE knobs Ensure ANGARABASE_TDE_ENABLE=1 is set in the environment before server startup.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Audit (TDE interaction): audit.md
• Hardening runbook: hardening.md
• Configuration reference: ../operations/configuration.md
• Security knobs registry: angarabook/src/operations/security-operations.md

Break-glass

Goal

Understand and use controlled privilege escalation (break-glass) to temporarily bypass RLS policies with full auditability.

Prerequisites

• SQL session with a user who has been granted the BREAK_GLASS capability.
• A healthy audit subsystem (break-glass cannot activate if audit is unavailable).

What is break-glass?

Break-glass is AngaraBase’s mechanism for controlled, time-limited, fully audited bypass of row-level security policies. It exists because SUPERUSER alone does not bypass RLS — this is a deliberate design choice.

Key properties:

• Activation requires a mandatory reason and a mandatory TTL.
• Every query executed during break-glass generates a dedicated break_glass_query audit entry.
• There is no “silent” bypass — the audit chain always records break-glass activity.
• This is a first-in-class database feature: neither PostgreSQL nor MS SQL Server have a built-in break-glass mechanism with TTL + reason + mandatory audit.

Steps

1) Grant the break-glass capability

A SECURITY_ADMIN grants the BREAK_GLASS role to a user or role:

GRANT BREAK_GLASS TO dba_team;

2) Activate break-glass

The user who has been granted BREAK_GLASS activates it with a reason and duration:

SET BREAK_GLASS REASON='INCIDENT-789: data corruption investigation' TTL='2h';

Duration format: '15m', '2h', '1d' etc. Maximum TTL is controlled by the server configuration (see below).

3) Check status

SELECT * FROM angara_break_glass_status();

Returns: is_active, reason, expires_at, activated_at.

4) Work under break-glass

While break-glass is active, RLS policies are bypassed. Every query in this session generates an audit entry with event_type = 'break_glass_query', including the full (sanitized) SQL text.

5) Deactivate (manual or automatic)

RESET BREAK_GLASS;

If not deactivated manually, break-glass auto-expires when the TTL elapses. After expiry, RLS applies again immediately.

6) Revoke the capability

REVOKE BREAK_GLASS FROM dba_team;

Configuration

Also exposed as security.break_glass_max_ttl in sys.settings.

Audit trail

All break-glass lifecycle events are recorded:

Invariants

1. Audit must be healthy. If the audit subsystem is down or corrupted, break-glass activation fails (fail-closed).
2. TTL is mandatory. SET BREAK_GLASS without TTL → error.
3. Reason is mandatory. SET BREAK_GLASS without REASON → error.
4. Max TTL is server-enforced. Exceeding security.break_glass_max_ttl → 22023 invalid_parameter_value.
5. No refresh. A client cannot extend the TTL — deactivate and re-activate with a new reason/TTL instead.
6. SUPERUSER ≠ RLS bypass. Only BREAK_GLASS bypasses RLS.

Expected result

• SET BREAK_GLASS with valid reason and TTL activates bypass; angara_break_glass_status() confirms.
• All queries during break-glass appear in sys.audit_log with event_type = 'break_glass_query'.
• After TTL expiry or RESET BREAK_GLASS, RLS enforcement resumes.
• Invalid TTL returns 22023; missing reason or TTL returns an error.

Troubleshooting

• 22023 invalid_parameter_value on SET BREAK_GLASS The TTL exceeds security.break_glass_max_ttl or is in an invalid format. Check the max TTL setting and use a supported duration format ('15m', '2h', '1d').
• 42501 insufficient_privilege on SET BREAK_GLASS The current user has not been granted BREAK_GLASS. A SECURITY_ADMIN must run GRANT BREAK_GLASS TO <user>.
• Break-glass activation fails with “audit unavailable” The audit subsystem must be healthy. Check ANGARABASE_AUDIT_LOG_PATH and audit key material if TDE is enabled.
• Break-glass expired unexpectedly TTL is server-enforced and cannot be refreshed. Deactivate and re-activate with a new reason and TTL.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Authorization (RLS policies): authorization.md
• Audit: audit.md
• Known issues: ../reference/known-issues.md

Deployment hardening runbook

Goal

Walk through a step-by-step process to launch AngaraBase in a production-secure configuration, and verify the result from SQL.

Prerequisites

• Access to server configuration (TOML config and/or environment variables).
• TLS certificate and key files.
• A 256-bit master key (64 hex characters) for TDE.
• Ability to restart the server.

Security hardening checklist

Before starting, confirm each item applies to your deployment:

• TLS enabled for all remote connectivity.
• Auth mode set explicitly (scram or cert) — not left as trust for production.
• TDE enabled with valid key material.
• Audit log path set and writable.
• DML audit policy chosen deliberately (off, allowlist, or denylist).
• Break-glass max TTL configured appropriately.
• angara_audit_verify_chain() runs clean.

Steps

Step 1 — Enable TLS

[tls]
enabled = true
cert_path = "/etc/angarabase/tls/server.crt"
key_path = "/etc/angarabase/tls/server.key"
require_on_remote_bind = true

This protects the wire protocol and enforces fail-closed on non-loopback bind without TLS.

See authentication.md for TLS details.

Step 2 — Set auth mode

export ANGARABASE_AUTH_MODE=scram

Disables trust-only behaviour for production. The superuser must have been bootstrapped at --init time with a SCRAM password.

See authentication.md for auth modes and SCRAM setup.

Step 3 — Enable TDE

export ANGARABASE_TDE_ENABLE=1
export ANGARABASE_TDE_MASTER_KEY_HEX=<64-hex-secret>
export ANGARABASE_TDE_MASTER_KEY_ID=master-prod-2026q1
export ANGARABASE_TDE_LAST_ROTATION_UNIX=1760000000

Enables at-rest encryption for pages, WAL, and audit sink. Without a valid key the server refuses to start (fail-closed).

See encryption.md for TDE configuration and key management.

Step 4 — Configure audit policy

export ANGARABASE_AUDIT_LOG_PATH=/var/lib/angarabase/audit/audit.jsonl
export ANGARABASE_AUDIT_DML_MODE=allowlist
export ANGARABASE_AUDIT_DML_ALLOWLIST=public.users,public.payments
export ANGARABASE_AUDIT_EXPORT_JSON_ENABLED=1
export ANGARABASE_AUDIT_EXPORT_RATE_LIMIT_RPS=50

Sets targeted DML audit coverage and bounded JSON export.

See audit.md for audit policy options and chain verification.

Step 5 — Verify effective config from SQL

After starting the server, confirm all settings from a SQL session:

SELECT name, value
FROM sys.settings
WHERE name IN (
 'tls.enabled',
 'tls.require_on_remote_bind',
 'security.auth_mode',
 'security.tde_enabled',
 'security.tde_master_key_id',
 'audit.dml_mode',
 'audit.export_json_enabled',
 'audit.export_rate_limit_rps'
)
ORDER BY name;

Only non-secret metadata appears. The TDE hex key, passwords, and SCRAM verifiers are never exposed.

Step 6 — Verify audit chain

SELECT * FROM angara_audit_verify_chain();

A healthy deployment returns is_valid = true.

Step 7 — Verify security surfaces

SELECT * FROM angara_user_roles() LIMIT 20;
SELECT * FROM angara_break_glass_status();

Confirm that introspection functions are responsive and return expected data.

Expected result

• Server starts only in fail-closed mode for unsafe configurations.
• sys.settings shows only non-secret metadata.
• Disk contains no plaintext audit payloads when TDE is enabled.
• Audit chain is intact; DML events appear for tables in the allowlist.
• Authentication rejects unauthenticated connections in scram/cert mode.

Troubleshooting

• Server does not start after enabling TDE Verify ANGARABASE_TDE_MASTER_KEY_HEX is exactly 64 hex characters and matches the data directory’s key. Fail-closed is expected.
• Auth/TLS conflict on remote bind If binding to a non-loopback address, tls.enabled must be true or --allow-insecure-no-auth must be passed (dev only). Check tls.require_on_remote_bind and server.host.
• DML audit events missing Verify audit.dml_mode is not off and that the target table matches the allowlist/denylist entries. Table names must be fully qualified (schema.table).
• angara_audit_verify_chain() returns is_valid = false The audit chain is corrupted. Note the first_broken_seq and investigate the audit file.
• Break-glass cannot activate The audit subsystem must be healthy. Fix the audit path or TDE key material first.
• Need a bug-report artifact? See ../reference/support.md.

Links

• Security model overview: overview.md
• Authentication: authentication.md
• Authorization: authorization.md
• Audit: audit.md
• Encryption: encryption.md
• Break-glass: break-glass.md
• Configuration reference: ../operations/configuration.md
• Security knobs registry: angarabook/src/operations/security-operations.md

GOST Security Compliance & Testing Guide

Status: TLS implemented, TDE planned Target Audience: Security Auditors, DevOps, QA

1. GOST Security Ecosystem in AngaraBase

AngaraBase implements a layered approach to Russian national cryptographic standards (GOST).

1.1. Transport Layer (TLS) — Available

Protection of data in transit using GOST R 34.10-2012 (Public Key) and GOST 28147-89 (Cipher suites).

• Implementation: Provider-based abstraction (OpenSSL Engine / Rustls).
• Policy: Fail-closed (server refuses to start if configured GOST provider is missing).
• Configuration: tls.gost_enabled, tls.gost_cipher_suites.

1.2. Data-at-Rest (TDE) — Planned

Protection of data on disk (Pages, WAL, Audit Logs) using block ciphers Kuznyechik (GOST 34.12-2015) or Magma.

• Scope: Transparent Data Encryption (TDE) for storage files.
• Key Management: Integration with external KMS supporting GOST keys.
• Status: Roadmap item.

1.3. Integrity & Authentication — Future

• Hashing: Migration from SHA-256 to Streebog (GOST R 34.11-2012) for data checksums and SCRAM authentication.
• Audit Signing: Digital signature of audit logs to ensure non-repudiation.

2. Testing GOST TLS Support

This guide describes how to verify that AngaraBase is correctly using GOST cipher suites and strictly enforcing the fail-closed policy.

Prerequisites

You need a Linux environment with OpenSSL configured for GOST.

# Debian/Ubuntu
sudo apt-get install openssl libssl-dev libengines-gost

# Verify engine availability
openssl engine gost -t
# Output should contain: [gost] Reference implementation of GOST engine -> [ available ]

Step 1: Generate GOST Certificates

Standard RSA/ECDSA certificates will not work with GOST cipher suites. You must generate keys using GOST algorithms.

# 1. Generate a private key using GOST R 34.10-2012 (256 bit)
openssl genpkey -algorithm gost2012_256 -pkeyopt paramset:A -out gost_server.key

# 2. Generate a self-signed certificate
openssl req -new -x509 -days 365 \
 -key gost_server.key \
 -out gost_server.crt \
 -subj "/CN=localhost"
 
# 3. Verify the certificate algorithm
openssl x509 -in gost_server.crt -text -noout | grep "Signature Algorithm"
# Expected: Signature Algorithm: GOST R 34.10-2012 with GOST R 34.11-2012 (256 bit)

Step 2: Configure AngaraBase

Enable TLS and GOST mode. Ensure allow_insecure is OFF to test strict mode.

export ANGARABASE_TLS_ENABLE=1
export ANGARABASE_TLS_CERT_PATH=$(pwd)/gost_server.crt
export ANGARABASE_TLS_KEY_PATH=$(pwd)/gost_server.key
export ANGARABASE_TLS_GOST_ENABLED=1
export ANGARABASE_TLS_GOST_CIPHER_SUITES="GOST2012-GOST8912-GOST8912"

# Start the server
./angarabase-server

Step 3: Verification (Positive Test)

Connect using a client that supports GOST (e.g., openssl s_client or a patched psql).

Using OpenSSL s_client:

openssl s_client -connect localhost:5152 -servername localhost

Verification Checklist:

1. Look for Cipher : GOST2012-GOST8912-GOST8912 (or similar GOST suite) in the output.
2. Look for Protocol : TLSv1.2.
3. Ensure the handshake completes successfully.

Using SQL (if psql supports it):

SELECT name, value FROM sys.settings WHERE name LIKE 'tls.%';
-- Verify tls.gost_enabled is 'true'

Step 4: Fail-Closed Verification (Negative Test)

Verify that the server refuses to start if the environment is broken.

1. Scenario A: Missing Provider. Temporarily disable the GOST engine (e.g., by renaming the library or changing OpenSSL config) and try to start AngaraBase with ANGARABASE_TLS_GOST_ENABLED=1.

• Expected Result: Server panic/exit with “GOST provider not available”.

2. Scenario B: Invalid Cipher Suite. Set ANGARABASE_TLS_GOST_CIPHER_SUITES="INVALID-CIPHER".

• Expected Result: Server panic/exit with configuration error.

3. Scenario C: RSA Certificate with GOST Ciphers. Try to start with ANGARABASE_TLS_GOST_ENABLED=1 but provide standard RSA certificates.

• Expected Result: Handshake failures (OpenSSL error: “no shared cipher” or “wrong signature type”).

3. Troubleshooting

Дальше

После того как вы определились, какие GOST-сценарии вам нужны:

• GOST crypto setup — пошаговая установка криптопровайдера и переключение профиля.
• Шифрование (TDE + клиентское) — общий контракт TDE и клиентского шифрования.
• Аудит — как замкнуть GOST-подписи на audit-chain.
• Hardening runbook — финальный чек-лист перед production.

Установка

AngaraBase распространяется через пакетные репозитории. Публичный доступ предоставляется бесплатно и без регистрации.

Поддерживаемые ОС

• RHEL-совместимые (8+): Red Hat Enterprise Linux, CentOS Stream, AlmaLinux, Rocky Linux, Oracle Linux, Fedora.
• Gentoo Linux: поддерживается через официальный binhost.

RPM (RHEL / CentOS / Alma / Fedora)

Установка производится через стандартный пакетный менеджер dnf.

1. Импорт GPG-ключа

Сначала необходимо импортировать публичный ключ, которым подписаны пакеты:

rpm --import https://rpm.angarabase.dev/release-key.asc

2. Подключение репозитория

Создайте файл конфигурации репозитория:

cat > /etc/yum.repos.d/angarabase.repo << 'EOF'
[angarabase]
name=AngaraBase
baseurl=https://rpm.angarabase.dev/el$releasever/stable/
enabled=1
gpgcheck=1
gpgkey=https://rpm.angarabase.dev/release-key.asc
EOF

3. Установка пакета

Установите серверный пакет:

dnf install angarabase-server

Gentoo Linux

Для Gentoo предоставляется готовый binhost со скомпилированными пакетами.

1. Импорт GPG-ключа

gpg --fetch-keys https://rpm.angarabase.dev/release-key.asc

2. Подключение binhost

Добавьте репозиторий в конфигурацию Portage:

cat >> /etc/portage/binrepos.conf << 'EOF'
[angarabase]
priority = 9999
sync-uri = https://rpm.angarabase.dev/gentoo/stable/
EOF

3. Установка пакета

Установите пакет, используя бинарную версию:

emerge --getbinpkg angarabase

Enterprise-репозиторий

Если у вас есть enterprise-подписка, вы получаете доступ к закрытому репозиторию с бинарными сборками. Доступ защищён с помощью mTLS (взаимная аутентификация по сертификатам).

Инструкция по подключению к Enterprise-репозиторию предоставляется вместе с invitation code при оформлении подписки. Если вы клиент, но у вас нет инструкции, напишите нам на team@angarabase.com.

Подробнее: angarabase.dev/enterprise

Configuration

Goal

Configure a AngaraBase instance for local testing or production deployment using TOML config keys, data-directory conventions, and environment variable overrides.

Prerequisites

• Built angarabase-server binary (see Quickstart)

Minimal config keys

Server

[server]
addr = "127.0.0.1:5152" # host:port; use 0.0.0.0:PORT to bind all interfaces

Storage

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

Logging

[logging]
log_level = "info"
log_directory = "/var/log/angarabase"

Ops (metrics / admin listeners)

[ops]
metrics_addr = "127.0.0.1:9898" # Prometheus metrics endpoint; empty = disabled
# admin_addr = "127.0.0.1:9999" # reserved, not yet active

Transaction log (durability)

[transaction_log]
backend = "noop"
durability = "strict"
fsync = true

TLS (optional)

[tls]
enabled = true
cert_path = "/etc/angarabase/tls/server.crt"
key_path = "/etc/angarabase/tls/server.key"

# If true and server.host is non-loopback, TLS is required (fail-closed).
require_on_remote_bind = true

WAL (Write-Ahead Log)

[wal]
vlf_enable = true
max_size_mb = 512
vlf_size_mb = 32
init_vlfs = 2
auto_shrink = true

SQL Execution

[execution]
mode = "auto" # auto | force_vector | force_row
vector_batch_size = 1024
query_memory_limit_mb = 256

Adaptive Query Processing (AQP)

[aqp]
enabled = true
mode = "conservative" # conservative | aggressive
min_query_time_ms = 100
learning_rate = 0.1
max_correction = 100.0
variance_threshold = 10.0
correction_cache_mb = 64
store_capacity_mb = 1024

Diagnostics

[diagnostics]
log_min_duration_ms = -1 # -1 = disabled
log_query_text = false
stat_statements_max = 0 # 0 = disabled

Initialization workflow

Run --init before the first normal start:

angarabase-server --config /path/to/angarabase.conf --init

• Directories data_directory and transaction_log_directory must be writable.
• When a valid logging.log_directory is set, the server writes angarabase-server.log.
• --init creates all required data-directory artifacts (see below).

For local dev/test shortcuts see Quickstart.

Data directory artifacts

Inside storage.data_directory the server creates and maintains:

Legacy text artifacts (identity_v0.txt, sys_catalog/*.txt) are no longer the source of truth and are not created by --init. If they remain from older versions they are ignored.

Environment variables

Environment variables override the corresponding config keys. When both are set, the env variable wins.

Precedence rule: default → config → env override

All parameters can be configured in angarabase.conf. Environment variables are intended for operational override without restart (for dynamic parameters) or for diagnostics. For permanent configuration, use the TOML config file.

Core server knobs

TLS knobs

Transaction log knobs

WAL (Write-Ahead Log) knobs

Diagnostics / slow-query knobs

Optimizer planning knobs

Vector execution knobs

Parallel execution governance knobs

Adaptive query processing knobs

OpenTelemetry tracing knobs

See also Diagnostics for query performance analysis.

Authentication knobs

Startup safety: trust/no-auth mode now requires explicit --allow-insecure-no-auth; without this flag the server refuses to start when ANGARABASE_AUTH_MODE resolves to trust/no-auth.

Security / break-glass knobs

Audit knobs

AngaraIO v2 I/O Scheduler knobs

Note: High-priority queue is unbounded per RFC invariant to ensure critical operations never block.

TDE (Transparent Data Encryption) knobs

Security note: when ANGARABASE_TDE_ENABLE=1 and ANGARABASE_AUDIT_LOG_PATH is set, the audit sink is encrypted at rest; without valid key material audit read/write is fail-closed (no plaintext fallback).

Expected result

After a successful --init and start:

curl -sS http://127.0.0.1:9898/health/ready # порт совпадает с [ops].metrics_addr

Returns {"status":"ready"}. Effective configuration is visible via:

SELECT * FROM sys.settings;

Troubleshooting

For unresolved issues see Known issues and Support.

Links

• Security/ops knobs registry (full defaults, fail-closed gates, sys.settings contract): angarabook/src/operations/security-operations.md
• Operator runbook: angarabook/src/operations/troubleshooting.md
• Security overview: Security model
• Quickstart: Quickstart

Container Deployment Quickstart

Операторский quickstart для image-first запуска AngaraBase:

• локальный docker run с cgroup-aware startup probe;
• минимальный k8s deployment (single-node, без HA);
• smoke-проверки readiness и базовой диагностики.

0) 30-second evaluator path (image-only)

Если нужен быстрый evaluator/DPP smoke без Rust toolchain:

tools/compat_suite/image_smoke.sh

Скрипт поднимает контейнер из канонического Dockerfile, ждёт /health/ready, проверяет startup log (deployment probe resolved effective budgets, cgroup_version) и наличие probe-метрик в /metrics.

1) Local container smoke (docker run)

Сборка образа:

docker build -t angarabase:local .

Запуск с memory limit (контракт probe-а):

docker run --rm --name angarabase-local \
  --memory=512m \
  -e ANGARABASE_DEPLOYMENT_PROFILE=container \
  -p 5152:5152 \
  -p 9898:9898 \
  angarabase:local

Ожидаемый признак в логах:

• есть строка deployment probe resolved effective budgets;
• deployment_profile=container;
• memory_source/cpu_source отражают cgroup_v1 или cgroup_v2 (либо proc_fallback с fallback_reason).

Проверка readiness в контейнере:

curl -fsS http://127.0.0.1:9898/health/ready

HEALTHCHECK контейнера использует этот же endpoint, поэтому становится green только после прохождения health_readiness_reason_v0().

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

curl -fsS http://127.0.0.1:9898/metrics | rg "deployment_probe|deployment_profile"

2) Resource-limit examples

CPU + memory cap:

docker run --rm --name angarabase-capped \
  --memory=1g \
  --cpus=1.5 \
  -e ANGARABASE_DEPLOYMENT_PROFILE=container \
  -p 5152:5152 \
  -p 9898:9898 \
  angarabase:local

Explicit override (probe не должен перезаписать):

docker run --rm \
  --memory=512m \
  -e ANGARABASE_DEPLOYMENT_PROFILE=container \
  -e ANGARABASE_MEMORY_BUDGET=256MB \
  -e ANGARABASE_CPU_BUDGET=1000m \
  -p 5152:5152 \
  -p 9898:9898 \
  angarabase:local

Ожидаемо: в метриках/логах источник budget-а становится config_override.

3) Kubernetes minimal smoke

Применение манифестов:

kubectl apply -f tools/deploy/kubernetes/minimal/namespace.yaml
kubectl apply -f tools/deploy/kubernetes/minimal/configmap.yaml
kubectl apply -f tools/deploy/kubernetes/minimal/service.yaml
kubectl apply -f tools/deploy/kubernetes/minimal/statefulset.yaml

Проверка:

kubectl -n angarabase get pods
kubectl -n angarabase get svc angarabase
kubectl -n angarabase logs statefulset/angarabase
kubectl -n angarabase get statefulset angarabase -o yaml | rg "resources:|health/"

Важно: в statefulset.yaml заданы resources.requests/limits. Если убрать лимиты, probe может увидеть “unlimited” и перейти на host-level fallback для budget-ов.

Удаление:

kubectl delete namespace angarabase

4) Diagnostics and backup entrypoints

Для packaged/operator path используйте angara-cli вместо прямых вызовов tools/...:

angara-cli diagnostics bundle --root artifacts/diagnostics/container-smoke --json
angara-cli backup full --config /etc/angarabase/angarabase.conf --out /tmp/base_full.abk

Связанные runbooks:

• Diagnostics bundle runbook
• Backup and restore

DPP alignment:

• safety rails по ресурсным лимитам и fail-closed режиму см. business_strategy/PILOT_CHECKLIST.md (§5 и §6).

Backup and restore

Goal

Create and restore backups of a AngaraBase instance — from cold/offline baselines through online FULL + LOG chain with point-in-time recovery (PITR).

Prerequisites

• Initialized AngaraBase instance (angarabase-server --init; see Configuration)
• Built angara-cli binary (see Quickstart)
• For online backups (phase 1b): a running server with WAL (transaction_log backend ≠ noop)

Cold / offline backup

The original supported method. The server must be stopped (or will be stopped by the runner).

1. Copy storage.data_directory and storage.transaction_log_directory.
2. After restore, run the txlog-level oracle.
3. The source must be a correctly initialized data directory.

Pinned commands (legacy shell)

Backup:

tools/backup_restore/run.sh backup \
 --data-dir /var/lib/angarabase/data \
 --txlog-dir /var/lib/angarabase/transaction_log \
 --out /tmp/angarabase-backup.tar.gz \
 --root artifacts/backup_restore/backup

Restore:

tools/backup_restore/run.sh restore \
 --archive /tmp/angarabase-backup.tar.gz \
 --dest /tmp/angarabase-restore \
 --force \
 --root artifacts/backup_restore/restore

Oracle (post-restore verification):

tools/backup_restore/oracle.sh --root artifacts/backup_restore_oracle/run_1

Remote Admin Backup Flow (Online Backup via Admin API)

AngaraBase supports triggering backups remotely via the Admin TCP endpoint. This is the recommended approach for production deployments, as it does not require direct file system access to the database node.

Requirements

• The angarabase-server must be running with the Admin API enabled (configured via admin.listen_address in angarabase.conf or ANGARABASE_ADMIN_ADDR environment variable).
• angara-cli must be executed with the --addr <host:port> parameter instead of --config.
• The user executing the backup must have network access to the Admin API port (default: 9899).

How it works

When using --addr, angara-cli connects to the running server’s Admin API and issues a RUN backup_full command. The server coordinates the backup process internally (Fuzzy Copy, WAL Inclusion) and streams the resulting .angarabk file back to the client over the network.

This allows operators to take backups from a central management node without SSH access to the database servers.

Storage layout note

User tables use the page-based .adb path. Legacy heap_store/*.bin is migrated to .adb on first access.

For backup/restore and triage:

• Both files per database are critical: <db>.adb and <db>.atl.
• heap_store/ is not the source of truth after migration.
• Upgrading old instances may take time proportional to heap_store volume.
• If the backup was taken with TDE enabled (ANGARABASE_TDE_ENABLE=1), restore requires the same valid key material; without it, startup after restore is fail-closed.

Backup/Restore v2 — phase 1a: one-file backupset

Minimal offline pipeline producing a single *.angarabk file (manifest-first format).

Capabilities

Pinned commands (phase 1a)

# FULL (offline/local baseline)
angara-cli backup full \
 --config /path/to/angarabase.conf \
 --out /tmp/full_0001.angarabk \
 --db-id base

# FULL (remote execution via Admin API)
angara-cli backup full \
 --addr 127.0.0.1:9899 \
 --out /tmp/full_0001.angarabk \
 --db-id base

# INSPECT (manifest-only)
angara-cli backup inspect --file /tmp/full_0001.angarabk

# VERIFY v0 (struct/hash)
angara-cli backup verify --file /tmp/full_0001.angarabk --json

# RESTORE (local) into a new directory
angara-cli backup restore \
 --config /path/to/angarabase.conf \
 --file /tmp/full_0001.angarabk \
 --target-dir /tmp/restore_0001 \
 --overwrite

Evidence pack (N=3)

tools/backup_restore/evidence_v2_phase1a.sh --runs 3

Inspect vs verify

• backup inspect: manifest-only, no payload scan.
• backup verify: struct/hash integrity; proves backupset consistency, not SQL-level correctness.

Backup/Restore v2 — phase 1b: online FULL + LOG chain + PITR

Online pipeline with point-in-time recovery support.

Capabilities

Pinned commands (phase 1b)

# ONLINE FULL (best-effort, with backup fence)
# Local execution:
angara-cli backup full-online \
 --config /path/to/angarabase.conf \
 --out /tmp/full_online_0001.angarabk \
 --db-id base

# Remote execution (via Admin API):
angara-cli backup full-online \
 --addr 127.0.0.1:9899 \
 --out /tmp/full_online_0001.angarabk \
 --db-id base

# LOG chunk (LSN boundaries must be contiguous with FULL/prev LOG)
angara-cli backup log \
 --config /path/to/angarabase.conf \
 --out /tmp/log_0001.angarabk \
 --start-lsn <u64> --end-lsn <u64> \
 --db-id base

# Validate chain contiguity
angara-cli backup chain-validate \
 --chain /tmp/full_online_0001.angarabk,/tmp/log_0001.angarabk \
 --json

# PITR restore to target_lsn
angara-cli backup restore-chain \
 --config /path/to/angarabase.conf \
 --target-dir /tmp/restore_chain_0001 \
 --target-lsn <u64> \
 --chain /tmp/full_online_0001.angarabk,/tmp/log_0001.angarabk \
 --overwrite

Evidence pack (N=3)

tools/backup_restore/evidence_v2_phase1b.sh --runs 3

Expected result

After a successful restore the server should start cleanly and previously committed data should be present:

SELECT * FROM sys.health;
SELECT * FROM sys.identity;

For PITR restores, data reflects the state at target_lsn.

Troubleshooting

For unresolved issues see Known issues and Support.

Host migration (без dump/restore)

Альтернатива backup/restore для переноса AngaraBase на другой хост — прямое копирование файлов данных с использованием Instance Lease системы.

Когда применимо

• Single-node deployment — один инстанс AngaraBase
• Shared storage — NFS, SAN или ручное копирование файлов
• Same version — одинаковая версия AngaraBase на источнике и цели
• Maintenance window — можно остановить инстанс на время копирования

Пошаговая инструкция

1. Остановить source инстанс:

# Graceful shutdown для освобождения lease
kill -TERM <angarabase-pid>

# Дождаться завершения
ps aux | grep angarabase-server

2. Проверить освобождение lease (опционально):

-- На другом инстансе или через backup connection
SELECT lease_holder_id FROM sys.identity;

3. Скопировать файлы данных:

# Копировать data directory
rsync -av /source/data/ /target/data/

# Копировать transaction log directory
rsync -av /source/txlog/ /target/txlog/

# Проверить целостность
find /target/data -name "*.adb" -exec ls -la {} \;

4. Запустить на target хосте:

# Обновить конфигурацию если нужно
vim /target/angarabase.conf

# Запустить AngaraBase
angarabase-server --config /target/angarabase.conf

5. Проверить миграцию:

-- Проверить lease holder
SELECT lease_holder_hostname, recovery_mode FROM sys.identity;

-- Проверить целостность данных
SELECT COUNT(*) FROM your_tables;

-- Проверить состояние системы
SELECT * FROM sys.health;

Что проверить после старта

• lease_holder_hostname изменился на новый хост
• recovery_mode показывает тип восстановления
• Все таблицы доступны и содержат ожидаемые данные
• Нет ошибок в логах сервера
• Клиентские подключения работают корректно

Ограничения

• Downtime required — требует остановки сервиса на время копирования
• File consistency — файлы должны быть скопированы атомарно
• Version compatibility — версии AngaraBase должны совпадать
• Configuration — пути в конфигурации могут потребовать обновления

Сравнение с backup/restore

См. также

Подробные инструкции по host migration: Crash Recovery — Host Migration

Links

• Canonical operator runbook: angarabook/src/operations/backup-restore.md

• Configuration reference: Configuration

• Diagnostics (post-restore health check): Diagnostics

• Host migration details: Crash Recovery

Crash Recovery and Storage Portability

This guide covers crash recovery scenarios and how to safely restart AngaraBase instances on existing data files, including migration to different hosts.

Overview

AngaraBase includes an Instance Lease system that prevents dual-write corruption while enabling safe crash recovery and storage portability. The system works on any filesystem, including NFS and SAN where traditional file locking is unreliable.

What Happens During Crash Recovery

When AngaraBase starts on existing data files, it performs these recovery phases:

Phase A: WAL Recovery (file_bin backend only)

• Scans transaction log files for incomplete entries
• Truncates partial tail records to maintain consistency
• Replays committed page deltas (redo operations)

Phase B: MVCC History Restore

• Recovers in-memory MVCC state from transaction log
• Marks uncommitted transactions as aborted
• Restores visibility information for concurrent reads

Phase C: Instance Lease Check

• Checks for active instance lease in base.adb
• Prevents dual instance startup with fail-closed error
• Automatically takes over expired leases (crash recovery)

Restarting on Existing Files (Same Host)

For normal restart scenarios on the same machine:

1. Stop the server (if running):

# Graceful shutdown releases the lease automatically
kill -TERM <angarabase-pid>

2. Start normally:

angarabase-server --config angarabase.conf

3. Verify recovery:

SELECT recovery_mode, lease_holder_id FROM sys.identity;

The instance lease will be automatically acquired after the TTL expires (default: 30 seconds).

Host Migration (Without dump/restore)

To move data files to a different host:

Prerequisites

• Both hosts have the same AngaraBase version
• Same page size (checked automatically)
• Shared storage OR manual file copy

Step-by-Step Process

1. Stop the source instance:

# Graceful shutdown to release lease
kill -TERM <angarabase-pid>

# Verify shutdown completed
ps aux | grep angarabase-server

2. Verify lease is released:

# Check that no process holds the lease
# (Optional: use another AngaraBase instance to query sys.identity)

3. Copy data files (if not using shared storage):

# Copy entire data directory
rsync -av /old/host/data/ /new/host/data/

# Copy transaction log directory 
rsync -av /old/host/txlog/ /new/host/txlog/

4. Start on new host:

angarabase-server --config angarabase.conf

5. Verify migration:

SELECT lease_holder_hostname, recovery_mode FROM sys.identity;
SELECT COUNT(*) FROM your_tables; -- Verify data integrity

Force Lease Takeover

If the previous instance crashed and the lease hasn’t expired, use force takeover:

When to Use

• Previous instance confirmed dead (host crashed, process killed)
• Lease shows expired time but takeover not automatic
• Emergency recovery scenarios

How to Use

# Set environment variable before starting
export ANGARABASE_FORCE_LEASE_TAKEOVER=1
angarabase-server --config angarabase.conf

Safety Checks

Before forcing takeover, verify:

• Previous instance process is definitely terminated
• No other AngaraBase processes accessing the same files
• Network partitions resolved (if applicable)

Warning: Force takeover with a running instance will cause data corruption.

Diagnostics

Check Lease Status

SELECT 
 lease_holder_id,
 lease_holder_hostname,
 lease_expires_at,
 lease_acquired_at,
 recovery_mode
FROM sys.identity;

Check Recovery Metrics

SELECT * FROM sys.health;

Lease Configuration

Environment variables (set before startup):

• ANGARABASE_LEASE_TTL_S: Lease duration in seconds (default: 30)
• ANGARABASE_LEASE_HEARTBEAT_S: Heartbeat interval (default: 10)
• ANGARABASE_FORCE_LEASE_TAKEOVER: Force takeover flag (default: false)

Limitations

WAL Backend Requirements

• Full recovery: Requires transaction_log.backend = "file_bin"
• Partial recovery: noop backend has no WAL replay (data loss possible)

Filesystem Considerations

• Local filesystems: Full support (ext4, xfs, btrfs, etc.)
• NFS/SAN: Instance lease works; verify file copy consistency
• Network partitions: May cause false lease expiration

Version Compatibility

• Same major.minor version required for host migration
• Page size must match (checked automatically)
• Configuration compatibility recommended

Troubleshooting

“Cannot start: database files are owned by another instance”

• Cause: Active lease held by another instance
• Solution: Wait for lease expiration or use force takeover (if safe)

“MVCC recovery failed”

• Cause: Corrupted transaction log files
• Solution: Check disk space, filesystem errors; may need backup restore

“VERSION decode failed”

• Cause: Corrupted version marker or incompatible format
• Solution: Restore from backup; check filesystem integrity

Performance After Recovery

• First queries may be slower (cold buffer pool)
• MVCC state rebuilds incrementally
• Statistics may need refresh (ANALYZE TABLE)

See Also

• Instance Lifecycle - Conceptual overview
• Backup and Restore - Host migration alternatives
• Configuration - Lease settings reference

Обновление бинарного релиза

Этот сценарий покрывает upgrade/downgrade без изменения on-disk формата в рамках текущей релизной линии.

Инварианты

• Обновление меняет бинарники и unit/scripts, но не трогает пользовательские данные.
• Каталог данных /var/lib/angarabase не удаляется.
• Конфиг /etc/angarabase/angarabase.conf сохраняется (noreplace-политика пакета).

Upgrade через DEB/RPM

DEB

sudo dpkg -i angarabase-server_<VERSION>_amd64.deb
sudo systemctl status angarabase --no-pager

RPM

sudo rpm -Uvh angarabase-server-<VERSION>-1.x86_64.rpm
sudo systemctl status angarabase --no-pager

Upgrade из tarball

sudo systemctl stop angarabase
sudo install -m 0755 bin/angarabase-server /usr/bin/angarabase-server
sudo install -m 0755 bin/angara-cli /usr/bin/angara-cli
sudo systemctl daemon-reload
sudo systemctl start angarabase

Проверка после обновления

angarabase-server --version
sudo systemctl is-active angarabase

Smoke-check:

• сервер поднимается без panic;
• конфиг и data dir доступны;
• базовый SQL health-check проходит.

Rollback

Rollback выполняется установкой предыдущего пакета/архива.

Важно: rollback допустим только между совместимыми версиями контрактов хранения.

Дальше

После успешного обновления и прохождения post-upgrade чек-листа:

• Crash recovery — что делать, если новая версия не стартанула.
• Резервное копирование и восстановление — снять контрольный backup сразу после апгрейда.
• Verify release artifacts — убедиться, что следующая версия скачана и проверена тем же способом.
• Operator deep-dive: Upgrade and migration — полный плейбук с rollback-сценариями.

Monitoring

Goal

Connect Prometheus and Grafana to AngaraBase metrics and get a working dashboard for ops/triage monitoring.

Prerequisites

• Running angarabase-server (see Quickstart)
• Access to the AngaraBase metrics listener (ANGARABASE_METRICS_ADDR)
• Running Prometheus instance
• Running Grafana instance

Step 1: enable the metrics endpoint

Set the listener address in the config file:

[ops]
metrics_addr = "127.0.0.1:9898"

Or use the environment variable override (takes precedence over config):

export ANGARABASE_METRICS_ADDR=127.0.0.1:9898
angarabase-server --config /etc/angarabase/angarabase.conf

Verify the endpoint responds:

curl -sS http://127.0.0.1:9898/metrics | rg '^angarabase_' -m 5
curl -sS http://127.0.0.1:9898/health/live
curl -sS http://127.0.0.1:9898/health/ready
curl -sS http://127.0.0.1:9898/health/startup

See Configuration — Ops knobs for the full [ops] section reference.

OpenTelemetry tracing

AngaraBase also exposes opt-in OTel-style span export for query lifecycle triage.

Minimal setup example:

export ANGARABASE_OTEL_ENABLED=1
export ANGARABASE_OTEL_EXPORTER=file
export ANGARABASE_OTEL_ENDPOINT=artifacts/otel/spans.jsonl
export ANGARABASE_OTEL_SAMPLE_RATE_PPM=1000000

Spans are emitted for bounded stage names (accept, auth, session, parse, plan, execute, storage_io, commit/rollback) and are intended for diagnostics evidence, not for raw SQL capture.

Step 2: configure the Prometheus scrape

Add a job to prometheus.yml:

scrape_configs:
 - job_name: angarabase
 scrape_interval: 15s
 metrics_path: /metrics
 static_configs:
 - targets: ["127.0.0.1:9898"]

Restart Prometheus and verify in the UI (/targets) that the angarabase target is UP.

Step 3: add the Prometheus data source in Grafana

1. Open the Grafana UI.
2. Navigate to Connections → Data sources.
3. Add Prometheus.
4. Set the URL to your Prometheus instance (e.g., http://127.0.0.1:9090).
5. Click Save & test and confirm the connection succeeds.

Step 4: import the AngaraBase dashboard

1. Go to Dashboards → New → Import.
2. Upload the file tools/observability/grafana/angarabase-overview-v2.json.
3. Select the Prometheus data source added in the previous step.
4. Save the dashboard.

Alternative — download the JSON directly from the server:

curl -fsS http://127.0.0.1:9898/grafana/angarabase-overview.json -o angarabase-overview.json

Then import angarabase-overview.json in Grafana.

Expected result

After import, the dashboard should display the following panels:

If panels are empty, see Troubleshooting below.

Troubleshooting

No data in panels

• Check http://<prometheus>/targets: the angarabase target must be UP.
• Ensure ANGARABASE_METRICS_ADDR matches the targets value in Prometheus.
• Verify metrics use the angarabase_ prefix:

curl -sS http://127.0.0.1:9898/metrics | rg '^angarabase_' -m 20

Data source test fails in Grafana

• Verify the data source URL and network reachability from Grafana to Prometheus.
• For Docker/K8s use the service DNS/hostname (not 127.0.0.1) when Grafana and Prometheus run in different containers.

Readiness probe is not ready

• GET /health/ready returns a reason in JSON — this is the primary triage signal.
• Collect a diagnostics bundle and attach summary.json:

tools/diagnostics_bundle/run.sh \
 --root artifacts/diagnostics/<incident-id> \
 --config <path> \
 --metrics-url http://<metrics-host>/metrics

• For further investigation see Diagnostics and Support.

Links

• Dashboard JSON: tools/observability/grafana/angarabase-overview-v2.json
• Dashboard JSON from server: GET /grafana/angarabase-overview.json (on ANGARABASE_METRICS_ADDR / [ops].metrics_addr)
• Dashboard import guide: tools/observability/README.md
• Operator runbook (metrics + probes): Troubleshooting guide
• Metrics checklist (contract): Observability metrics checklist
• Configuration reference: Configuration
• Support flow: Support

Diagnostics

Goal

Analyze query performance, inspect server state, and triage issues using AngaraBase’s built-in diagnostic tools.

Prerequisites

• Running angarabase-server (see Quickstart)
• psql or another pgwire-compatible client
• For slow-query logging: env variables set before server start (see Configuration)

EXPLAIN variants

Basic query plan

EXPLAIN SELECT * FROM t WHERE id = 1;

Shows the planned execution path without running the query.

EXPLAIN ANALYZE (with actual timing)

EXPLAIN ANALYZE SELECT * FROM t WHERE id > 100;

Executes the query and reports actual row counts and timing alongside the plan.

For parallel join plans, EXPLAIN ANALYZE also reports best-effort join accounting counters:

• join_build_rows — rows processed by join build phase,
• join_probe_rows — rows processed by join probe phase.

EXPLAIN ANALYZE for DML (dry-run)

EXPLAIN ANALYZE over INSERT, UPDATE, or DELETE runs the statement inside an isolated dry-run transaction that rolls back automatically — no data is modified.

EXPLAIN ANALYZE INSERT INTO t (id, v) VALUES (999, 42);
EXPLAIN ANALYZE UPDATE t SET v = v + 1 WHERE id = 1;
EXPLAIN ANALYZE DELETE FROM t WHERE id = 1;

Buffer statistics

EXPLAIN (BUFFERS) SELECT * FROM t WHERE id = 1;

Adds buffer-pool hit/miss counters to the plan output.

JSON output

EXPLAIN (FORMAT JSON) SELECT * FROM t WHERE id = 1;

Returns the plan as a JSON document — useful for programmatic analysis.

Runtime diagnostic views

angara_stat_activity

Shows currently executing queries and their wait state.

SELECT pid, state, wait_event_type, query
FROM angara_stat_activity;

wait_event_type values: Lock, IO, Net, CPU — provides coarse wait categorization for triage.

angara_stat_statements

Aggregated per-query statistics (call count, total time, rows, etc.).

SELECT query, calls, total_time, rows
FROM angara_stat_statements
ORDER BY total_time DESC
LIMIT 10;

Reset accumulated stats:

SELECT angara_stat_statements_reset();

The maximum number of tracked statements is controlled by ANGARABASE_STAT_STATEMENTS_MAX (LRU-bounded). See Configuration — Diagnostics knobs.

angara_top_queries

Convenience wrapper returning the top-N queries by cumulative time:

SELECT * FROM angara_top_queries(10);

Slow-query log

Capture queries that exceed a duration threshold to the server log.

Configuration

Set before server start (env variables override config):

Example:

export ANGARABASE_LOG_MIN_DURATION_MS=500
export ANGARABASE_LOG_QUERY_TEXT=1
angarabase-server --config /path/to/angarabase.conf

Slow queries appear in the server log at logging.log_directory.

Saturation / backpressure (operability)

When p99/p99.9 degrades under load, you usually want to distinguish:

• lock/contention waits,
• IO/scheduler saturation,
• admission/queue rejects vs “random” timeouts.

Practical entry points:

• angara_stat_activity.wait_event_type (coarse wait classification)
• operator runbook: angarabook/src/operations/troubleshooting.md

System introspection views

sys.health

Overall server health status:

SELECT * FROM sys.health;

sys.settings

Effective configuration (config + env overrides resolved):

SELECT * FROM sys.settings;
SELECT * FROM sys.settings WHERE name LIKE 'storage.%';

sys.identity

Instance identity metadata:

SELECT * FROM sys.identity;

Expected result

• EXPLAIN variants return plan text (or JSON) without errors.
• angara_stat_activity shows at least the current session.
• angara_stat_statements accumulates entries after queries are executed.
• sys.health returns {"status":"ready"} on a healthy instance.

Troubleshooting

For unresolved issues see Known issues and Support.

Links

• SQL compatibility reference: SQL overview
• Monitoring setup: Monitoring
• Configuration (env knobs): Configuration
• Diagnostics bundle tool: tools/diagnostics_bundle/run.sh
• Operator runbook: angarabook/src/operations/troubleshooting.md
• Инцидентный runbook (10 минут): Error debug runbook
• Support flow: Support

Structured Logging

Status: ✅ Active Scope: Production operations, diagnostics, troubleshooting

Overview

AngaraBase uses structured logging for production observability and diagnostics. This replaces ad-hoc println! calls with consistent, level-based log messages using the Rust log crate and env_logger backend.

Key Benefits

• Consistent Format: All log messages follow structured key=value format
• Level Control: Runtime-configurable verbosity (error/warn/info/debug/trace)
• Production Ready: Suitable for log aggregation systems (ELK, Splunk, etc.)
• Performance: Low overhead when disabled, structured context when enabled

Log Levels

Level Policy

Production Recommendations

• Production: info (default) - captures operational events without performance impact
• Troubleshooting: debug - detailed diagnostics for performance analysis
• Development: trace - full verbosity for debugging

Configuration

Static Configuration (angarabase.conf)

[logging]
log_level = "info"

Supported values: error, warn, info, debug, trace Default: info Restart required: No (dynamic setting)

Environment Variable Override

export ANGARABASE_LOG_LEVEL=debug
./angarabase-server --config /etc/angarabase/angarabase.conf

Environment variables take precedence over config file settings during bootstrap.

Runtime Configuration

Change log level without restart using SQL:

-- Check current setting
SELECT * FROM sys.settings WHERE name = 'logging.log_level';

-- Change to debug level
SELECT sys.set_setting('logging.log_level', 'debug');

-- Verify change
SELECT * FROM sys.settings WHERE name = 'logging.log_level';

Note: Runtime changes are volatile and reset on restart. Update angarabase.conf for persistent changes.

Log Format

Structure

All log messages follow this format:

2026-03-09T10:30:45.123Z INFO [angarabase_server::stats] stats_scheduler: auto_analyze_triggered table=users staleness_score=2.45

Components:

• Timestamp: ISO 8601 with millisecond precision
• Level: ERROR/WARN/INFO/DEBUG/TRACE
• Module: Rust module path (e.g., angarabase_server::stats)
• Context: Structured key=value pairs with operation context

Context Format

Log messages use consistent key=value structured context:

#![allow(unused)]
fn main() {
// Good: structured context
log::info!("instance_lease: acquired holder={} expires_at={}", holder_id, expires_at);

// Good: operation context
log::debug!("micro_rescan: completed table={} scanned_rows={} duration={:?}", table, rows, duration);

// Good: error context 
log::warn!("audit_sink: write_failed path={} err={}", path, error);
}

Context Guidelines:

• Use snake_case for keys
• Include operation prefix (e.g., micro_rescan:, instance_lease:)
• Provide enough context for troubleshooting
• Avoid sensitive data in logs (use IDs, not content)

Production Deployment

Log Aggregation

AngaraBase structured logs integrate well with log aggregation systems:

ELK Stack:

# logstash.conf
filter {
 if [program] == "angarabase-server" {
 grok {
 match => { "message" => "%{TIMESTAMP_ISO8601:timestamp} %{LOGLEVEL:level} \[%{DATA:module}\] %{GREEDYDATA:context}" }
 }
 kv {
 source => "context"
 field_split => " "
 value_split => "="
 }
 }
}

Splunk:

[angarabase]
EXTRACT-level = (?<level>ERROR|WARN|INFO|DEBUG|TRACE)
EXTRACT-module = \[(?<module>[^\]]+)\]
EXTRACT-operation = (?<operation>\w+):

Log Rotation

Configure log rotation for production deployments:

# /etc/logrotate.d/angarabase
/var/log/angarabase/*.log {
 daily
 rotate 30
 compress
 delaycompress
 missingok
 notifempty
 create 0644 angarabase angarabase
 postrotate
 systemctl reload angarabase-server
 endscript
}

Monitoring

Key log patterns to monitor:

# Error rate monitoring
grep "ERROR" /var/log/angarabase/server.log | wc -l

# Instance lease issues
grep "instance_lease.*failed" /var/log/angarabase/server.log

# Performance degradation
grep "stats_scheduler.*io_backpressure" /var/log/angarabase/server.log

# MVCC recovery events
grep "mvcc_recovery:" /var/log/angarabase/server.log

Troubleshooting

Common Issues

High log volume at debug level:

-- Reduce to info level
SELECT sys.set_setting('logging.log_level', 'info');

Missing log output:

# Check RUST_LOG environment variable
echo $RUST_LOG

# Override with explicit filter
export RUST_LOG=angarabase_server=debug,rustls=warn

Log format parsing issues:

• Ensure timestamp parsing handles millisecond precision
• Context parsing should handle key=value pairs with spaces
• Module names contain :: separators

Performance Impact

Log level performance characteristics:

Recommendation: Use info for production, temporarily increase to debug for troubleshooting specific issues.

Migration Notes

From println! to log::*!

Current implementation migrated all production println! calls to structured logging:

• 60+ calls across 11 files replaced
• Backward compatibility: No breaking changes to existing functionality
• Enhanced context: More structured information for operations

Future Enhancements (Phase 2)

Planned for next releases:

• Tracing integration: Distributed tracing with spans
• OpenTelemetry: OTLP export for APM systems
• Metrics correlation: Link logs with performance metrics
• Sampling: Adaptive sampling for high-volume environments

See Also

• RFC-2026-360: Structured Logging & Tracing v0
• Instance Lifecycle - Instance lease logging
• Crash Recovery - MVCC recovery logging
• Settings Management - Runtime configuration

AngaraBase Tracing Operations Guide

Audience: Database operators, SREs, performance engineers

Overview

AngaraBase включает structured tracing на базе tracing crate с поддержкой OpenTelemetry. Эта система заменяет legacy env_logger и обеспечивает end-to-end visibility для query execution pipeline.

Key Benefits:

• End-to-end spans: accept → authenticate → parse → plan → execute → storage → response
• Каждый запрос имеет уникальный trace_id
• JSON-структурированные логи для machine parsing
• Интеграция с Jaeger/Tempo через OpenTelemetry
• Автоматическая propagation tracing context через async/sync boundaries

Configuration

Basic Setup

В angarabase.conf:

[diagnostics]
# Tracing output format: "text" (human-readable) или "json" (structured)
tracing_format = "json"

# Log level filtering (same as RUST_LOG)
log_level = "info"

Environment Variables

JSON vs Text Format

Text format (human-readable):

2026-03-12T10:30:45.123Z INFO angarabase::query::executor: query_start session_id=12345 sql="SELECT * FROM users"
2026-03-12T10:30:45.125Z DEBUG angarabase::query::planner: plan_created plan_hash=abc123 estimated_rows=1000

JSON format (machine-parseable):

{"timestamp":"2026-03-12T10:30:45.123Z","level":"INFO","target":"angarabase::query::executor","fields":{"session_id":12345,"sql":"SELECT * FROM users"},"span":{"name":"query_execution","trace_id":"abc123"}}

Tracing Architecture

Span Hierarchy

query_execution (root span)
├── parse (SQL → AST)
├── plan (AST → execution plan)
├── execute
│ ├── storage_io (page reads/writes)
│ ├── lock_acquisition
│ └── wal_flush
└── commit (autocommit finalization)

Span Propagation

AngaraBase автоматически propagates tracing context через:

1. Async boundaries: tokio::task::spawn_blocking calls
2. Thread pool: Worker thread execution
3. Network layer: AngaraNet io_uring/tokio integration

Implementation pattern:

#![allow(unused)]
fn main() {
let span = tracing::Span::current();
tokio::task::spawn_blocking(move || {
 let _enter = span.enter();
 // Sync code here inherits tracing context
 engine.execute(&query)
}).await
}

Operational Procedures

Enabling Tracing

1. Development/Debug:

RUST_LOG=angarabase=trace ./angarabase-server

2. Production (JSON logs):

# angarabase.conf
[diagnostics]
tracing_format = "json"
log_level = "info"

3. OpenTelemetry Export:

export ANGARABASE_OTLP_ENDPOINT=http://jaeger:14268/api/traces
export ANGARABASE_TRACE_SAMPLE_RATE=0.05 # 5% sampling
./angarabase-server

Monitoring Query Performance

1. Slow Query Detection

Text logs:

grep "query_execution.*duration_ms" /var/log/angarabase.log | \
 awk '$NF > 1000' | head -10 # Queries > 1 second

JSON logs:

jq 'select(.span.name == "query_execution" and .fields.duration_ms > 1000)' \
 /var/log/angarabase.log

2. Per-Phase Timing Analysis

Look for spans with names: parse, plan, execute, commit

Example JSON query:

jq 'select(.span.name == "execute" and .fields.duration_ms > 500)' \
 /var/log/angarabase.log | \
 jq '.fields | {trace_id, duration_ms, estimated_rows}'

3. Lock Contention Detection

# Find queries waiting on locks
jq 'select(.fields.wait_event_type == "Lock")' /var/log/angarabase.log

Troubleshooting Common Issues

High Parse Time

# Find queries with slow parsing
jq 'select(.span.name == "parse" and .fields.duration_ms > 100)' \
 /var/log/angarabase.log | jq '.fields.sql'

Common causes:

• Complex SQL with many JOINs
• Large IN clauses
• Deeply nested subqueries

High Plan Time

# Find queries with slow planning
jq 'select(.span.name == "plan" and .fields.duration_ms > 200)' \
 /var/log/angarabase.log

Common causes:

• Missing statistics
• Complex join ordering
• Large number of tables

High Execute Time

# Correlate with storage I/O
jq 'select(.span.name == "storage_io" and .fields.duration_ms > 1000)' \
 /var/log/angarabase.log

Common causes:

• Sequential scans
• I/O bottlenecks
• Lock contention

Integration with External Tools

Jaeger Integration

1. Setup Jaeger:

docker run -d --name jaeger \
-p 14268:14268 -p 16686:16686 \
jaegertracing/all-in-one:latest

2. Configure AngaraBase:

export ANGARABASE_OTLP_ENDPOINT=http://localhost:14268/api/traces

3. View traces: http://localhost:16686

Grafana/Tempo Integration

# tempo.yaml
server:
 http_listen_port: 3200

distributor:
 receivers:
 otlp:
 protocols:
 http:
 endpoint: 0.0.0.0:4318

storage:
 trace:
 backend: local
 local:
 path: /tmp/tempo/traces

Log Aggregation (ELK Stack)

Logstash configuration:

input {
 file {
 path => "/var/log/angarabase.log"
 codec => "json"
 }
}

filter {
 if [span][name] {
 mutate {
 add_field => { "trace_operation" => "%{[span][name]}" }
 }
 }
}

output {
 elasticsearch {
 hosts => ["elasticsearch:9200"]
 index => "angarabase-traces-%{+YYYY.MM.dd}"
 }
}

Performance Impact

Overhead Measurements

Production Recommendations

1. Use JSON format for structured log processing
2. Set appropriate log levels: INFO for production, DEBUG for troubleshooting
3. Configure OTLP sampling: 1-10% for high-traffic systems
4. Monitor log volume: JSON logs are ~2x larger than text

Alerting and Monitoring

Key Metrics to Monitor

1. Query Duration Distribution:

histogram_quantile(0.95, 
rate(angarabase_query_duration_seconds_bucket[5m])
)

2. Slow Query Count:

increase(angarabase_slow_queries_total[5m])

3. Tracing Overhead:

rate(angarabase_tracing_events_total[5m])

Alerting Rules

groups:
- name: angarabase_tracing
 rules:
 - alert: HighQueryLatency
 expr: |
 histogram_quantile(0.95, 
 rate(angarabase_query_duration_seconds_bucket[5m])
 ) > 1.0
 for: 2m
 labels:
 severity: warning
 annotations:
 summary: "AngaraBase query latency is high"
 
 - alert: TracingVolumeHigh
 expr: |
 rate(angarabase_tracing_events_total[5m]) > 1000
 for: 5m
 labels:
 severity: info
 annotations:
 summary: "AngaraBase tracing volume is high"

Security Considerations

Sensitive Data in Logs

⚠️ WARNING: Tracing logs may contain SQL queries with sensitive data.

Mitigation strategies:

1. Query parameter redaction:

[diagnostics]
redact_query_params = true # Replace literals with ?

2. Log rotation and retention:

# logrotate configuration
/var/log/angarabase.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
}

3. Access control:

chmod 640 /var/log/angarabase.log
chown angarabase:angarabase-ops /var/log/angarabase.log

OTLP Export Security

# Use TLS for OTLP export
export ANGARABASE_OTLP_ENDPOINT=https://jaeger.internal:14268/api/traces
export ANGARABASE_OTLP_TLS_CERT=/etc/ssl/certs/angarabase.crt
export ANGARABASE_OTLP_TLS_KEY=/etc/ssl/private/angarabase.key

Troubleshooting

Common Issues

1. No Tracing Output

Symptoms: No tracing spans in logs Causes:

• RUST_LOG not set or too restrictive
• tracing_format misconfigured
• Tracing not enabled in binary

Solution:

# Check tracing is compiled in
./angarabase-server --version | grep tracing

# Enable debug tracing
RUST_LOG=angarabase=debug ./angarabase-server

2. Missing Span Context

Symptoms: Broken trace chains, missing parent-child relationships Causes:

• Missing span.enter() in spawn_blocking calls
• Incorrect async context propagation

Solution: Check for proper span propagation pattern in code

3. High Log Volume

Symptoms: Disk space issues, performance degradation Causes:

• Log level too verbose (TRACE in production)
• No log rotation
• High query volume

Solution:

# Reduce log level
export RUST_LOG=angarabase=info

# Enable log rotation
logrotate -f /etc/logrotate.d/angarabase

4. OTLP Export Failures

Symptoms: Traces not appearing in Jaeger/Tempo Causes:

• Network connectivity issues
• Incorrect endpoint configuration
• Authentication failures

Solution:

# Test OTLP endpoint
curl -v $ANGARABASE_OTLP_ENDPOINT/health

# Check AngaraBase logs for export errors
grep "otlp.*error" /var/log/angarabase.log

Advanced Topics

Custom Span Attributes

AngaraBase automatically adds these attributes to spans:

Correlation with System Metrics

CPU correlation:

# Find high-CPU queries
jq 'select(.span.name == "execute" and .fields.cpu_time_ms > 1000)' \
 /var/log/angarabase.log

I/O correlation:

# Find I/O-heavy queries 
jq 'select(.fields.io_reads > 1000 or .fields.io_writes > 100)' \
 /var/log/angarabase.log

Custom Dashboards

Grafana query examples:

1. Query throughput by operation:

sum(rate(angarabase_queries_total[5m])) by (operation)

2. Average query duration by phase:

avg(angarabase_query_phase_duration_seconds) by (phase)

3. Lock contention rate: