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 на уровне, достаточном для принятия решений: выбор конфигурации, диагностика проблем, оценка применимости.

Подробный разбор подсистем — в разделах Концепции и SQL Reference.

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

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-кодом, а не неожиданный результат. Это предсказуемо и безопасно для продакшена.

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

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

Quickstart: запуск за 5 минут

Поднимаем angarabase-server, подключаемся через psql, выполняем базовый DDL/DML и проверяем, что данные и каталог переживают рестарт.

Требования

• Linux x86_64, glibc ≥ 2.28. Portable-сборка проверяет это сама: при более старом glibc angarabase-server выходит fail-closed с явным сообщением о несовместимости.
• Один из вариантов установки: portable-архив x86_64-unknown-linux-gnu или сборка из исходников (Rust toolchain — см. rust-toolchain.toml).
• Клиент psql (или любой PostgreSQL-совместимый).

Установка

Portable-архив

VER=0.6.8
mkdir -p /opt/angarabase
tar -xzf angarabase-$VER-x86_64-unknown-linux-gnu.tar.gz -C /opt/angarabase
/opt/angarabase/angarabase-$VER/bin/angarabase-server --version

Сборка из исходников

cargo build --release -p angarabase-server -p angara-cli
# бинарь: target/release/angarabase-server

Шаг 1. Конфиг

AngaraBase не стартует с «магических» дефолтов — путь к данным и адрес задаются явно. Минимальный angarabase.conf:

[server]
addr = "127.0.0.1:5432"

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

[logging]
log_level = "info"

Путь к конфигу передаётся флагом --config-path; без флага сервер ищет /etc/angarabase/angarabase.conf. Если конфиг найден, но содержит устаревшие ключи, сервер падает fail-closed (exit 78) с их перечислением — молчаливого отката к дефолтам нет.

Шаг 2. Инициализация инстанса

Однократная инициализация создаёт каталог, data/ и txlog/ по путям из конфига. --init — отдельный однопроходный режим: бинарь инициализирует инстанс и завершает работу с кодом 0.

angarabase-server --config-path ./angarabase.conf --init \
  --superuser angara_root \
  --superuser-password-file ./superuser.pw \
  --auth-mode scram --require-auth

• --auth-mode scram — SCRAM-SHA-256 (режим по умолчанию; scram — алиас полного имени scram-sha-256).
• --require-auth — fail-closed: init откажется, если для не-trust режима не задан пароль суперпользователя.
• Пароль: --superuser-password-file <файл> (рекомендуется) или --superuser-password-env <VAR>. Инлайн-форма --superuser-password '...' тоже есть, но пароль попадёт в историю шелла.

Init печатает instance_id, data_directory, txlog_directory. Повторный init на уже инициализированном каталоге — fail-closed (already initialized).

⚠️ Insecure-режимы — только явно. trust/no-auth (без аутентификации) разрешён лишь с явным --insecure-trust: --auth-mode trust --insecure-trust. Без этого флага init откажется. Используйте только в изолированных лабах, не в сети.

Альтернатива без редактирования конфига — переопределить корень инстанса флагами; тогда data/ и txlog/ создаются под указанным каталогом:

angarabase-server --config-path ./angarabase.conf --init \
  --init-root /var/lib/angarabase \
  --superuser angara_root --superuser-password-file ./superuser.pw \
  --auth-mode scram --require-auth

Шаг 3. Запуск сервера

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

Сервер слушает 127.0.0.1:5432 (из конфига). Бинд на не-loopback адрес без TLS/auth тоже fail-closed: нужен явный --allow-insecure (или [security].allow_insecure = true). Это флаг для контролируемых сред, не для прода.

⚠️ --allow-insecure / --allow-insecure-no-auth / --dev включают небезопасные пресеты (без TLS, без обязательной аутентификации). Допустимы только в dev/test.

Шаг 4. Подключение через psql

psql "host=127.0.0.1 port=5432 user=angara_root dbname=base password=<пароль> sslmode=disable"

base — логическая база по умолчанию (схема public).

SecurityContext (режимы scram / cert)

В режимах scram/cert защищённый SQL (таблицы под RLS, tenant-scoped данные) требует контекста сессии — иначе политике безопасности не к чему привязаться. Установите claim сразу после подключения:

SET SESSION CONTEXT 'app.tenant_id' = 'public';
-- эквивалентная краткая форма:
SET app.tenant_id = 'public';

SET SESSION CONTEXT нельзя выполнять внутри открытой транзакции (вернётся ошибка). Значение читается через current_setting('app.tenant_id') — именно на нём строятся RLS-политики (см. Авторизация).

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;

Проверка рестартом (DDL переживает перезапуск)

Метаданные CREATE TABLE (каталог) должны сохраняться между перезапусками.

1. Остановите сервер (Ctrl+C).
2. Запустите снова: angarabase-server --config-path ./angarabase.conf.
3. Убедитесь, что таблица на месте:

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

Интроспекция через 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';

Опционально: shutdown через SQL (fail-closed)

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

export ANGARABASE_ALLOW_SQL_SHUTDOWN=1

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

SELECT sys.request_shutdown();

Операция проходит проверку RBAC и пишется в audit-log; пользователю без прав — отказ.

Если что-то не так

• «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. Несколько команд в одном запросе

psql -c "..." (и любой клиент) может отправить несколько SQL-команд, разделённых ;, одним Simple Query. AngaraBase выполняет их по порядку и возвращает результат каждой:

psql 'postgresql://angara@127.0.0.1:5432/angara_demo' \
  -c "CREATE TABLE t(id int); INSERT INTO t VALUES (1); SELECT count(*) FROM t"
# CREATE TABLE
# INSERT 0 1
#  count
# -------
#      1

• Ошибка в любой команде прерывает выполнение остатка строки (как в PostgreSQL).
• Отличие от PostgreSQL — атомарность. PostgreSQL неявно оборачивает всю multi-statement строку (без явного BEGIN) в одну транзакцию: при ошибке откатываются и ранее выполненные команды. AngaraBase же фиксирует каждую команду по отдельности (autocommit), поэтому при ошибке в середине строки ранее выполненные команды остаются зафиксированными. Для атомарной миграции оборачивайте набор явно: BEGIN; …; COMMIT (тогда ошибка откатит всё).
• Ограничения разбиения. Строка делится по ;, при этом ; внутри одинарных кавычек (SELECT 'a;b') не разбивает запрос. Но ; внутри строчного (--) или блочного (/* */) комментария, внутри идентификатора в двойных кавычках ("a;b") или внутри dollar-quoted-тела ($$ … ; … $$, например PL/pgSQL-функции и вывод pg_dump) разобьёт строку некорректно. Такие команды отправляйте отдельными запросами или через psql -f.

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

• 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. Автоматические проверки сборки документации помечают расхождение как блокирующее.

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

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

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

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

Restrictive by default + fail-closed

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

• свою границу (например, max_connections, txn.max_write_set_bytes, execution.query_memory_limit_mb),
• поведение при её нарушении (явная ошибка с известным 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).

Если вы опираетесь на что-то из этого списка в продакшене — это технический долг на стороне клиента, и очередное обновление 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 (строковое хранилище). In-Memory (AngaraMemory) доступен (bounded) через storage='memory'; Column-Store запланирован.

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 в заголовке страницы. Отдельного файла для индексов нет.

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 (AngaraMemory) — доступен (bounded)

Движок для хранения данных в оперативной памяти (storage='memory'). Поддерживаются три режима durability:

Статус: доступен (bounded).

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 и не требует блокировок. Читатель никогда не ждёт писателя и наоборот.

Операции записи (оптимистичный конкурентный доступ)

Писатели не удерживают классических блокировок строк. Конкуренция — оптимистичная: во время транзакции изменения копятся в overlay, а на COMMIT движок проверяет по версиям, что затронутые данные не изменились с момента snapshot транзакции.

• Если параллельная транзакция успела закоммитить конфликтующее изменение, «проигравшая» откатывается с 40001 (serialization failure) — данные не теряются молча. Счётчик: angarabase_txn_commit_conflicts_total.
• Гранулярность конфликта — построчная по умолчанию: параллельные писатели в разные строки одной таблицы оба коммитятся успешно.
• Предикатные UPDATE/DELETE, которые не могут перечислить конкретные целевые строки (скан по условию), консервативно эскалируют до табличного конфликта: любое параллельное изменение этой таблицы откатит одну из транзакций. Это и есть serialized-fallback — более грубая, но безопасная проверка.

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. Если нужна строгая сериализуемость, самый прямой путь — уровень SERIALIZABLE (SSI предотвращает write skew и phantom-ы, конфликтные транзакции прерываются с 40001). Как альтернатива — явные блокировки SELECT ... FOR UPDATE (работают для простых однотабличных запросов с id в проекции; для JOIN/подзапросов возвращается 0A000)

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)

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

AngaraTree — index engine

AngaraTree — индексный движок AngaraBase. Индексы хранятся внутри .adb-файла базы данных (страницы с page_type = 1), вместе с 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).

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

Обслуживание индекса ограничено по времени (fail-closed): если вставка/удаление в индекс не укладывается в бюджет, DML откатывается, а счётчик angarabase_index_reject_total инкрементируется.

Реджект angarabase_index_reject_total покрывает также внутренние пределы (KeyTooLarge, PageLimitExceeded); отдельного публичного кноба на число страниц нет.

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

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

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

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

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

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

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

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

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

Перестроение индекса

Полное перестроение индекса выполняется командой REINDEX:

REINDEX INDEX idx_name;
REINDEX CONCURRENTLY INDEX idx_name;   -- без долгой блокировки DML

Полезно после частичного восстановления при старте (метрика angarabase_index_restore_capped_total ≠ 0 означает, что индекс поднят не полностью) или для возврата места после массовых удалений (merge страниц в v0 нет — место освобождает REINDEX).

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

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

• Обработка запросов — как оптимизатор выбирает и комбинирует индексы.
• Хранение данных — как страницы 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 # включить текст запроса в лог

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

Vectorized и параллельное исполнение

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

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

• Индексы — как оптимизатор выбирает индекс для 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.*) — первые шаги с системными представлениями
• Безопасность — функции интроспекции безопасности
• Диагностика — мониторинг и устранение проблем
• Обработка запросов — как оптимизатор использует метаданные каталога

Жизненный цикл инстанса

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

Идентичность инстанса

При инициализации инстанс получает устойчивую идентичность:

• cluster_id — UUID логического кластера БД.
• instance_id — UUID конкретного инстанса.
• Каталог данных и каталог журнала транзакций — физическое расположение файлов.

Идентичность хранится в двух местах, чтобы пережить как сбой файла, так и сбой каталога:

1. VERSION-маркер — бинарный файл с версией формата и идентификаторами.
2. Страницы системного каталога — в зарезервированных страницах base.adb с полными метаданными.

Аренда инстанса (Instance Lease)

Аренда не даёт двум инстансам одновременно писать в одни и те же файлы — а это прямой путь к повреждению данных. Запись аренды лежит в SysCatalogMetaV0 внутри страниц base.adb и обновляется атомарно полным образом страницы. Поэтому механизм работает на NFS/SAN, где flock() ненадёжен.

Что записано в аренде

Состояния аренды

 [Нет]  ──acquire──▶  [Held]  ──heartbeat──▶  [Held]
   ▲                    │
   └──release/expired───┘
                        │ heartbeat прекратился (краш, разрыв сети)
                        ▼
                  [Expired]  ──takeover──▶  [Held новым инстансом]

• Нет → Held — первый запуск или запуск после штатной остановки.
• Held → Held — периодический heartbeat (по умолчанию каждые 10 с) сдвигает expires_at.
• Held → Нет — штатная остановка немедленно освобождает аренду.
• Held → Expired — heartbeat прекратился (краш, сетевой разрыв); аренда «протухает» по истечении TTL.
• Expired → Held — новый инстанс перехватывает аренду после истечения TTL.

Порядок запуска

1. Pre-flight — каталог данных существует и инициализирован, VERSION-маркер совместим, размер страницы совпадает со сборкой бинаря.
2. Захват аренды — загрузка системного каталога из base.adb, затем:
   • аренды нет → захватить сразу;
   • аренда истекла → перехватить (с предупреждением в лог);
   • аренда активна → fail-closed с информативной ошибкой (см. ниже);
   • принудительный перехват → переопределить активную аренду (опасно).
3. Восстановление — проигрывание WAL (backend file_bin), восстановление in-memory состояния MVCC, запуск heartbeat.
4. Готов к подключениям — поднимаются слушатели (pgwire, admin), сервер принимает клиентов и продолжает heartbeat до остановки.

Режимы восстановления

recovery_mode виден в sys.identity и принимает три значения:

Разделяемое хранилище (NFS/SAN)

Аренда позволяет нескольким хостам видеть одни и те же файлы, но писать — только одному:

Host A ──┐
         ├── NFS/SAN ──▶ [data/] [txlog/] [base.adb с арендой]
Host B ──┘

• Failover — Host B перехватывает аренду, если Host A упал.
• Обслуживание/миграция — перенос инстанса между хостами без дампа.
• Тестирование — безопасный прогон на копии боевых данных.

Ограничения: единственный писатель в каждый момент; сетевые разрывы могут вызвать ложное истечение аренды; латентность сетевого хранилища влияет на пропускную способность.

Управление арендой (env-переменные)

Аренда настраивается только переменными окружения — отдельных config-ключей для неё нет.

Рекомендации: в сети с нестабильной задержкой увеличьте TTL и heartbeat (например, 60/20); для быстрой итерации в dev — уменьшите (15/5). Heartbeat должен оставаться заметно меньше TTL.

⚠️ ANGARABASE_FORCE_LEASE_TAKEOVER=1 опасен. Он переопределяет активную аренду, игнорируя живого владельца. Если прежний инстанс на самом деле жив, вы получите двух писателей в одни файлы и повреждение данных. Включайте только когда владелец подтверждённо мёртв (процесс не запущен, хост недоступен). В норме просто дождитесь истечения TTL — перехват произойдёт сам.

Наблюдаемость и диагностика

-- Текущий владелец аренды и режим восстановления
SELECT lease_holder_id, lease_holder_hostname, lease_expires_at, recovery_mode
FROM sys.identity;

-- Здоровье инстанса
SELECT uptime_seconds, txn_commit_epoch_current
FROM sys.health;

События аренды пишутся в лог сервера: захват, перехват, отказ heartbeat, освобождение.

Типичные проблемы

Безопасность: аренда не аутентифицирует — права доступа ФС и сетевые ограничения по-прежнему обязательны, особенно на разделяемом хранилище.

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

Концепции

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

How-to

• Crash recovery — операционные процедуры восстановления после аварии.
• Резервное копирование и восстановление — как защитить datadir и снять снапшот.

Справочник

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

Обзор совместимости SQL

AngaraBase реализует подмножество PostgreSQL SQL через pgwire-протокол. Принцип — fail-closed: неподдерживаемая конструкция возвращает явный SQLSTATE (чаще всего 0A000 feature_not_supported), а не молчаливый некорректный результат. Эта страница — карта того, что поддержано, и как быстро интерпретировать ошибки.

Стандартные SQL-конструкции

Матрица того, что AngaraBase понимает в запросах. Поддерживается — корректная семантика с pinned-тестами; Частично — работает с ограничениями (см. заметку); 0A000 — неподдержанная форма возвращает детерминированную ошибку.

Запросы (SELECT)

JOIN

Оконные функции (OVER (…))

DDL / DML / типы

Подробные таблицы и Expected SQLSTATE — на страницах раздела:

Ключевые DDL-границы: CREATE MATERIALIZED VIEW поддержан, обычный CREATE VIEW — planned (0A000), CREATE TRIGGER — non-goal (0A000), FOREIGN KEY — принимается как NOT ENFORCED.

Коды ошибок (SQLSTATE) — быстрый справочник

Полный список с контекстом: Известные ограничения и SQLSTATE.

Подключение ORM и инструментов

ORM и клиенты (DBeaver, psql, Hibernate, Django и др.) при подключении выполняют служебные pg_catalog-запросы. AngaraBase поддерживает базовую интроспекцию pg_catalog, нужную для подключения этих инструментов. Если клиент не подключается, проверьте Совместимость клиентов.

Если запрос зависает (нет ответа), это ошибка с нашей стороны — пожалуйста, соберите артефакты по инструкции в Поддержке и сообщите нам.

Встроенные функции SQL

Видимость векторного выполнения

Когда режим выполнения допускает векторный путь (ANGARABASE_SQL_EXECUTION_MODE=auto для поддержанных планов или force_vector), EXPLAIN показывает имена векторных операторов: VectorSeqScan, VectorFilter, VectorProject, VectorHashJoin, VectorAgg. Если форму плана AngaraVector не поддерживает, в EXPLAIN остаются строчные (row) операторы.

Режимы ANGARABASE_SQL_EXECUTION_MODE:

• auto (по умолчанию) — Stable векторный путь только для полностью поддержанных форм, иначе детерминированный откат на строчный;
• force_row — Stable всегда строчный исполнитель;
• force_vector — Experimental fail-closed с feature_not_supported, если векторное выполнение невозможно; для целевого тестирования, не для production-нагрузки в 0.6.x.

Опции таблиц AngaraMemory

CREATE TABLE ... WITH (...) поддерживает bounded-таблицы в памяти:

• storage='memory' — Baseline движок таблиц AngaraMemory;
• durability='none'|'logged'|'snapshotted' — Baseline volatile/durable;
• max_rows=<n> — Stable жёсткий лимит строк; переполнение fail-closed (54023);
• eviction_policy='error'|'fifo' — Experimental по умолчанию error;
• checkpoint_interval_ms=<n> — Baseline имеет смысл только при durability='snapshotted'.

Если max_rows не задан, применяется bounded-дефолт из политики инстанса. При durability='snapshotted' горячий путь DML не персистит страницы немедленно — запись планирует checkpoint-воркер по checkpoint_interval_ms.

Ссылки

• Известные ограничения и SQLSTATE
• Поддержка
• Модель безопасности

Data types

Справочник типов данных AngaraBase: что реально поддержано, что — нет, и какой SQLSTATE возвращается при приведении. Источник истины — реестр типов движка (SQL_TYPE_REGISTRY); уровни поддержки сверены по нему, а не по наличию OID в виртуальном pg_catalog.

Поддерживаемые типы

Stable — production-ready, есть pinned-тест. Baseline — реализован и пригоден, но тестовое покрытие уже.

MVARCHAR — национальный VARCHAR для 1С

MVARCHAR — собственный тип AngaraBase для совместимости с 1С: сравнение регистронезависимое и без учёта хвостовых ASCII-пробелов, длина задаётся как MVARCHAR(N), для индекса применяется отдельная нормализация ключа.

CREATE TABLE catalog (code MVARCHAR(16), name MVARCHAR(255));
-- 'Тест ' и 'тест' сравниваются как равные

Text-backed temporal types

DATE / TIMESTAMP / TIMESTAMPTZ хранятся в text-backed режиме:

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

Planned (пока недоступны)

Эти типы зарегистрированы в pg_catalog для интроспекции, но не пригодны к использованию — приведение к ним возвращает 0A000:

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;
SELECT '550e8400-e29b-41d4-a716-446655440000'::UUID;

Expected SQLSTATE

Links

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

DDL — Data Definition Language

Справочник поддерживаемых 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 — не обязателен; до одного на таблицу, inline (col TYPE PRIMARY KEY) или table-level (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 MATERIALIZED VIEW public.mv_sum AS
  SELECT SUM(val) AS s FROM public.src;

-- пересчёт по требованию:
REFRESH MATERIALIZED VIEW public.mv_sum;

-- запланированный пересчёт:
CREATE MATERIALIZED VIEW public.mv_events
  WITH (refresh_mode = 'scheduled', refresh_interval = '1s') AS
  SELECT SUM(v) AS s FROM public.events;

REFRESH MATERIALIZED VIEW нельзя выполнять внутри транзакции.

CREATE / ALTER / DROP SEQUENCE

AngaraBase поддерживает first-class объекты-последовательности (SEQUENCE) — 0.6.3.7. Они сохраняются в 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

Справочник поддерживаемых 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

0.6.3.7 (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)

0.6.3.7 (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;

Начиная с 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

0.6.3.7 (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

0.6.3.7: 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

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

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

Поддерживаются все пять видов: INNER, LEFT [OUTER], RIGHT [OUTER], FULL [OUTER], CROSS.

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;

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

Условие соединения задаётся только через ON <expr> (для CROSS JOIN условие не нужно). USING (...) и NATURAL JOIN не поддерживаются — 0A000.

CROSS JOIN ограничен бюджетом числа строк sql.join.max_cross_join_rows (по умолчанию 1 000 000; env ANGARABASE_MAX_CROSS_JOIN_ROWS); превышение — 54000 program_limit_exceeded.

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;

DISTINCT поддерживается; DISTINCT ON (...) — 0A000.

Подзапросы

Поддерживаются IN (...), EXISTS / NOT EXISTS и скалярные подзапросы в SELECT-списке (в т.ч. коррелированные):

SELECT * FROM orders o WHERE EXISTS (SELECT 1 FROM items i WHERE i.order_id = o.id);
SELECT id, (SELECT COUNT(*) FROM items i WHERE i.order_id = o.id) AS n FROM orders o;
SELECT * FROM t WHERE id IN (SELECT order_id FROM items);

Множества (UNION / INTERSECT / EXCEPT)

SELECT id FROM a
UNION       -- с дедупликацией
SELECT id FROM b;

SELECT id FROM a UNION ALL  SELECT id FROM b;   -- без дедупликации
SELECT id FROM a INTERSECT  SELECT id FROM b;
SELECT id FROM a EXCEPT     SELECT id FROM b;

Оконные функции (OVER (...))

Поддерживаются ROW_NUMBER, RANK, DENSE_RANK, LAG, LEAD, FIRST_VALUE, LAST_VALUE и оконные агрегаты SUM/COUNT/AVG/MIN/MAX с PARTITION BY / ORDER BY:

SELECT id, grp,
       ROW_NUMBER() OVER (PARTITION BY grp ORDER BY id) AS rn,
       SUM(amount)  OVER (PARTITION BY grp)             AS grp_total
FROM t;

Не поддерживаются (0A000): NTILE, именованные окна (WINDOW-clause).

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

Встроенные статистические представления — то, на что опирается планировщик при оценке кардинальности. Полезны, чтобы понять, по каким колонкам собрана статистика (histogram/MCV/HLL) и насколько она свежа (*_epoch); пустые histogram/MCV означают, что для колонки ещё не набран Level 2.

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

Справочник секционирования таблиц: 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;

Расширение AngaraBase. В стандартном PostgreSQL отдельного DROP PARTITION нет — там это два шага: ALTER TABLE ... DETACH PARTITION + DROP TABLE. Здесь DROP PARTITION <name> удаляет дочернюю партицию одной командой.

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 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',
 '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 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 chain is append-only — tampering is detected (not silently repaired); recovery is an operator action.
• 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

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 ANGARABASE_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 ANGARABASE_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',
 '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: TLS-совместимость и тестирование

Что доступно сейчас: транспортное шифрование (TLS) на ГОСТ-наборах. TDE на ГОСТ (Кузнечик/Магма для страниц/WAL/аудита) и переход контрольных сумм/SCRAM на Стрибог — roadmap, не реализованы. Эта страница — про настройку и проверку именно GOST-TLS.

Аудитория: специалисты по безопасности, DevOps, QA.

1. GOST в AngaraBase: что есть и что планируется

1.1. Транспорт (TLS) — доступно

Защита данных в канале на ГОСТ Р 34.10-2012 (открытый ключ) и наборах шифров ГОСТ 28147-89.

• Реализация: провайдер-абстракция (OpenSSL Engine / Rustls).
• Политика: fail-closed — сервер откажется стартовать, если настроенный GOST-провайдер недоступен.
• Конфиг: tls.gost_enabled, tls.gost_cipher_suites.

1.2. Данные на диске (TDE) — planned

Шифрование страниц, WAL и журналов аудита блочными шифрами Кузнечик (ГОСТ 34.12-2015) или Магма — пункт roadmap. Управление ключами через внешний KMS с поддержкой ГОСТ. Сейчас не реализовано.

⚠️ Серверный TDE в текущих версиях использует XOR-keystream, а не ГОСТ-шифр и не AES/AEAD. См. Шифрование.

1.3. Целостность и аутентификация — future

Переход контрольных сумм и SCRAM с SHA-256 на Стрибог (ГОСТ Р 34.11-2012) и цифровая подпись журналов аудита — планы, не реализованы.

2. Тестирование GOST-TLS

Как убедиться, что AngaraBase действительно использует ГОСТ-наборы и строго соблюдает fail-closed.

Предусловия

Нужна Linux-среда с OpenSSL, настроенным под ГОСТ.

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

# Проверка доступности движка
openssl engine gost -t
# В выводе должно быть: [gost] Reference implementation of GOST engine -> [ available ]

Шаг 1. Сгенерировать ГОСТ-сертификаты

Обычные RSA/ECDSA-сертификаты не подойдут к ГОСТ-наборам — ключи нужно сгенерировать ГОСТ-алгоритмами.

# 1. Приватный ключ по ГОСТ Р 34.10-2012 (256 бит)
openssl genpkey -algorithm gost2012_256 -pkeyopt paramset:A -out gost_server.key

# 2. Самоподписанный сертификат
openssl req -new -x509 -days 365 \
  -key gost_server.key \
  -out gost_server.crt \
  -subj "/CN=localhost"

# 3. Проверить алгоритм сертификата
openssl x509 -in gost_server.crt -text -noout | grep "Signature Algorithm"
# Ожидается: Signature Algorithm: GOST R 34.10-2012 with GOST R 34.11-2012 (256 bit)

Шаг 2. Настроить AngaraBase

Включить TLS и ГОСТ-режим. Чтобы проверить строгий режим, убедитесь, что allow_insecure выключен.

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"

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

tls.gost_enabled по умолчанию выключен (явный opt-in); дефолтный набор — GOST2012-GOST8912-GOST8912:GOST2001-GOST89-GOST89.

Шаг 3. Позитивная проверка

Подключитесь клиентом с поддержкой ГОСТ (например, openssl s_client или пропатченный psql).

openssl s_client -connect localhost:5152 -servername localhost

Чек-лист:

1. В выводе есть Cipher : GOST2012-GOST8912-GOST8912 (или другой ГОСТ-набор).
2. Protocol : TLSv1.2.
3. Handshake завершается успешно.

Через SQL (если клиент поддерживает):

SELECT name, value FROM sys.settings WHERE name LIKE 'tls.%';
-- Проверьте, что tls.gost_enabled = 'true'

Шаг 4. Проверка fail-closed (негативные тесты)

Убедитесь, что сервер отказывается стартовать при сломанном окружении.

1. Нет провайдера. Временно отключите ГОСТ-движок (переименуйте библиотеку или измените конфиг OpenSSL) и запустите с ANGARABASE_TLS_GOST_ENABLED=1. → Ожидается: отказ старта с «GOST provider not available».
2. Невалидный набор шифров. ANGARABASE_TLS_GOST_CIPHER_SUITES="INVALID-CIPHER". → Ожидается: отказ старта с ошибкой конфигурации.
3. RSA-сертификат с ГОСТ-наборами. ANGARABASE_TLS_GOST_ENABLED=1, но обычные RSA-сертификаты. → Ожидается: провал handshake («no shared cipher» / «wrong signature type»).

3. Диагностика

Дальше

После того как вы определились, какие 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

Конфигурация

Настройка инстанса AngaraBase для локального теста или production: ключи TOML-конфига, директории данных и переопределения через переменные окружения. Нужен собранный angarabase-server (см. Quickstart).

Минимальный конфиг

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:9899" # Admin TCP API (remote backups via angara-cli --addr); empty = disabled

Журнал транзакций (durability)

[transaction_log]
backend = "file_bin"   # durable binary WAL; нужен для crash-recovery MVCC
durability = "strict"  # strict | relaxed | group_commit
fsync = true

Компилируемый дефолт backend — noop (без durability, для ephemeral/тестов). Для любого реального инстанса ставьте file_bin — только с ним работает восстановление MVCC после аварии (см. Crash recovery).

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

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

Инициализация

Перед первым обычным запуском выполните --init:

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

• Каталоги data_directory и transaction_log_directory должны быть доступны на запись.
• При заданном logging.log_directory сервер пишет angarabase-server.log.
• --init создаёт все необходимые артефакты каталога данных (см. ниже).

Шорткаты для dev/test — в Quickstart.

Артефакты каталога данных

Внутри storage.data_directory сервер создаёт и поддерживает:

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.

Переменные окружения

Переменные окружения переопределяют соответствующие ключи конфига; если заданы оба — выигрывает переменная окружения.

Приоритет: default → config → env override

Все параметры можно задать в angarabase.conf. Переменные окружения нужны для оперативного переопределения и диагностики; для постоянной конфигурации используйте TOML-файл. Эффективные значения и их источник видны в sys.settings.

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).

Ожидаемый результат

После успешного --init и запуска:

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

Возвращает {"status":"ready"}. Эффективная конфигурация видна через:

SELECT * FROM sys.settings;

Диагностика

Нерешённое — в Известных ограничениях и Поддержке.

См. также

• Security operations baseline — security/ops-кнобы, fail-closed гейты, контракт sys.settings.
• Диагностика — анализ производительности запросов.
• 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:

Скрипт поднимает контейнер из канонического 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 -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 вместо прямых вызовов dev-скриптов:

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 режиму см. docs/gtm/PILOT_CHECKLIST.md (§5 и §6).

Backup and restore

Резервное копирование и восстановление инстанса AngaraBase — от холодного (offline) бэкапа до онлайн-цепочки FULL + LOG с восстановлением на момент времени (PITR).

Требуется инициализированный инстанс и бинарь angara-cli. Для онлайн-бэкапа — запущенный сервер с WAL ([transaction_log] backend = file_bin, не noop).

Какой способ выбрать

Для новых развёртываний по умолчанию — phase 1b (онлайн + PITR). Phase 1a — когда достаточно простого offline-снимка. Legacy shell-обёртки оставлены для совместимости.

Флаг конфигурации у angara-cli — --config / -c (у angarabase-server — --config-path); для удалённого выполнения через Admin API вместо --config указывается --addr <host:port>.

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:

Restore:

Oracle (post-restore verification):

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

• angarabase-server должен быть запущен с включённым Admin API ([ops] admin_addr в angarabase.conf или переменная ANGARABASE_ADMIN_ADDR; если адрес не задан, admin-листенер не поднимается).
• angara-cli запускается с --addr <host:port> вместо --config.
• Нужен сетевой доступ к порту Admin API (по умолчанию 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)

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)

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-path /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

См. также

• Конфигурация — TDE-ключи, [ops] admin_addr, backend WAL.
• Диагностика — health-check после restore.
• Crash recovery — детали host migration.

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 bundled AngaraBase overview dashboard JSON (see the download step below).
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:

• For further investigation see Diagnostics and Support.

Links

• Dashboard JSON from server: GET /grafana/angarabase-overview.json (on ANGARABASE_METRICS_ADDR / [ops].metrics_addr)
• 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
• Operator runbook: angarabook/src/operations/troubleshooting.md
• Инцидентный runbook (10 минут): Error debug runbook
• Support flow: Support

Логирование

AngaraBase пишет структурированные логи через tracing / tracing_subscriber (формат key=value), пригодные для систем агрегации (ELK, Splunk и т.п.).

Уровни

Рекомендации: info — в production; debug — на время разбора инцидента; trace — только в разработке.

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

Уровень и фильтр задаёт переменная окружения RUST_LOG (читается на старте, по умолчанию info). Поддерживается синтаксис EnvFilter — в т.ч. фильтры по модулям:

# глобальный уровень
RUST_LOG=debug ./angarabase-server --config-path /etc/angarabase/angarabase.conf

# по модулям: debug для сервера, warn для TLS
export RUST_LOG="angarabase_server=debug,rustls=warn"
./angarabase-server --config-path /etc/angarabase/angarabase.conf

Фильтр фиксируется при запуске — чтобы изменить уровень, перезапустите сервер с новым RUST_LOG.

Настройка logging.log_level (env ANGARABASE_LOG_LEVEL, конфиг [logging]) валидируется и видна в sys.settings, но консольный subscriber слушает именно RUST_LOG. Для фактического изменения вербозности сервера используйте RUST_LOG и перезапуск.

-- посмотреть записанное значение настройки
SELECT name, value FROM sys.settings WHERE name = 'logging.log_level';

Формат строки

2026-03-09T10:30:45.123Z INFO angarabase_server::stats stats_scheduler: auto_analyze_triggered table=users staleness_score=2.45

• Timestamp — ISO 8601, миллисекунды.
• Level — ERROR/WARN/INFO/DEBUG/TRACE.
• Module — путь модуля Rust (например, angarabase_server::stats).
• Context — структурированные пары key=value с префиксом операции (например, instance_lease:, micro_rescan:). Чувствительные данные в логи не попадают — только идентификаторы.

Production

Ротация (logrotate)

# /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
}

Агрегация

ELK (logstash):

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-operation = (?<operation>\w+):

Полезные грепы

grep "ERROR" /var/log/angarabase/server.log | wc -l        # частота ошибок
grep "instance_lease.*failed" /var/log/angarabase/server.log
grep "mvcc_recovery:" /var/log/angarabase/server.log

Влияние на производительность

См. также

• Tracing — распределённая трассировка (spans, OTLP).
• Мониторинг — метрики Prometheus.
• Жизненный цикл инстанса — события аренды в логах.
• Crash recovery — логи восстановления MVCC.

Tracing

AngaraBase использует tracing. Есть два уровня наблюдаемости:

1. Логи сервера — вербозность задаёт RUST_LOG (см. Логирование).
2. Трассы запросов (OTel-спаны) — опциональный per-query экспорт спанов accept → parse → plan → execute → storage → commit.

Экспорт идёт только в stderr (через лог) или в локальный JSONL-файл. Сетевого OTLP-коллектора, Jaeger/Tempo, push по HTTP — нет.

Включение трасс запросов

Per-query трассы выключены по умолчанию. Управление — переменными окружения:

# 5% запросов в локальный JSONL-файл
export ANGARABASE_OTEL_ENABLED=1
export ANGARABASE_OTEL_SAMPLE_RATE_PPM=50000
export ANGARABASE_OTEL_EXPORTER=file
export ANGARABASE_OTEL_ENDPOINT=/var/log/angarabase/query-traces.jsonl
./angarabase-server --config-path /etc/angarabase/angarabase.conf

При EXPORTER=stderr строки спанов попадают в обычный лог сервера (на уровне info).

Что в спане

Каждая трасса запроса несёт идентификаторы, по которым её можно связать с sys.*-диагностикой:

• логическая БД и пользователь;
• класс запроса (QueryClass);
• queryid и planid (если доступны) — те же идентификаторы, что в angara_stat_statements и EXPLAIN.

Разбор JSONL

# медленные запросы (>1s) из файла трасс
jq 'select(.duration_ms > 1000)' /var/log/angarabase/query-traces.jsonl

# распределение по queryid
jq -r '.queryid' /var/log/angarabase/query-traces.jsonl | sort | uniq -c | sort -rn | head

Для агрегатных метрик (latency-перцентили, частота медленных запросов) используйте Prometheus-эндпоинт — см. Мониторинг, а для точечного анализа плана — Диагностику.

Безопасность

⚠️ Спаны и логи могут содержать текст SQL с чувствительными данными.

• Ограничьте доступ к файлу трасс: chmod 640, владелец — сервисный пользователь.
• Настройте ротацию (см. logrotate в Логировании).
• Не включайте 100%-сэмплинг с текстом SQL на проде без необходимости — это и объём, и риск утечки.

Если трасс нет

• ANGARABASE_OTEL_ENABLED не установлен в 1/true — спаны не пишутся.
• ANGARABASE_OTEL_SAMPLE_RATE_PPM=0 — сэмплинг выключен.
• EXPORTER=file, но ANGARABASE_OTEL_ENDPOINT не задан или путь недоступен на запись — строка уходит в stderr-лог вместо файла.
• Слишком строгий RUST_LOG для stderr-экспортёра — поднимите уровень (см. Логирование).

См. также

• Логирование — RUST_LOG, формат строк, ротация, агрегация.
• Мониторинг — метрики Prometheus.
• Диагностика — EXPLAIN, angara_stat_*, медленный лог.

USDT / eBPF probes

AngaraBase встраивает USDT-пробы (User Statically-Defined Tracing) — точки инструментации для eBPF-инструментов (bpftrace, bcc, perf).

• Zero-overhead, пока не подключён трейсер: в бинаре это NOP-инструкции.
• Без рестарта: трейсер цепляется к работающему процессу.
• Провайдер — angarabase; пробы компилируются с feature usdt (включён по умолчанию). Сборка --no-default-features их исключает.

Проверка наличия проб

# пробы встроены?
readelf -n ./angarabase-server | grep -A5 stapsdt

# список доступных проб
bpftrace -l 'usdt:./angarabase-server:angarabase:*'

Теги запросов (query_tag)

Каждая проба несёт tag — u64-хеш (xxh64) метки запроса. По умолчанию 0 (нетегированный трафик; operator_*-пробы для него вообще не срабатывают). Тег позволяет фильтровать только интересующие запросы.

-- на сессию:
SET query_tag = 'demo-heavy-report';
RESET query_tag;

-- на отдельный запрос (hint в комментарии):
/*+ angarabase:tag=demo-heavy-report */ SELECT * FROM orders;

В bpftrace фильтр /* tag */ != 0 оставляет только тегированный трафик.

Сигнатуры основных проб

Аргументы в bpftrace — arg0, arg1, … в порядке ниже.