Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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; пользователю без прав — отказ.

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

Дальше

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