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

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

Настройка инстанса 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 сервер создаёт и поддерживает:

ArtifactPurpose
VERSIONInitialization marker (format_version, min_server_version); enforces fail-closed startup.
base.adbOn-disk system database file.

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

VariableDefaultDescription
ANGARABASE_SHUTDOWN_TIMEOUT_MS1000Bounded graceful-shutdown timeout (ms).
ANGARABASE_ALLOW_SQL_SHUTDOWNoffAllow shutdown trigger via SELECT sys.request_shutdown().
ANGARABASE_STORAGE_STRICT_STARTUPenabledStorage verification on startup. Set 0/false/off to disable.
ANGARABASE_METRICS_ADDR—Override for [ops].metrics_addr.
ANGARABASE_SUPPORT_CONTACThttps://github.com/angarabase/angarabase/issuesSupport contact shown by linux-gnu glibc compatibility guard when runtime glibc < 2.28. Override only if you run a forked distribution with its own support channel.
ANGARABASE_IN_MEMORY_MAX_ROWS_PER_TABLE100000Default hard cap for storage='memory' tables when max_rows is omitted. Must be positive.

TLS knobs

VariableDefaultDescription
ANGARABASE_TLS_ENABLEoffEnable TLS upgrade via pgwire SSLRequest.
ANGARABASE_TLS_CERT_PATH—PEM certificate chain (required when TLS enabled).
ANGARABASE_TLS_KEY_PATH—PEM private key (required when TLS enabled).

Transaction log knobs

VariableDefaultDescription
ANGARABASE_TRANSACTION_LOG—Override txlog backend (noop / file / file_bin).
ANGARABASE_TRANSACTION_LOG_DURABILITY—Override durability (strict / relaxed / group_commit).
ANGARABASE_TRANSACTION_LOG_FSYNC—Override fsync for strict mode (0 / 1).

WAL (Write-Ahead Log) knobs

VariableDefaultDescription
ANGARABASE_WAL_VLF_ENABLEenabledEnable VLF (Virtual Log Files) circular layout. Set 0 to disable and use linear WAL.
ANGARABASE_WAL_MAX_SIZE_MB512Maximum WAL file size in MB. Controls circular buffer size for VLF.
ANGARABASE_WAL_VLF_SIZE_MB32Individual VLF segment size in MB. Must be smaller than WAL_MAX_SIZE_MB.
ANGARABASE_WAL_INIT_VLFS2Initial number of VLF segments to allocate at startup.

Diagnostics / slow-query knobs

VariableDefaultDescription
ANGARABASE_LOG_MIN_DURATION_MS-1 (disabled)Slow-query log threshold in milliseconds.
ANGARABASE_LOG_QUERY_TEXT0Include raw SQL text in slow log (0 / 1).
ANGARABASE_STAT_STATEMENTS_MAX—Max in-memory entries for angara_stat_statements (LRU bounded).

Optimizer planning knobs

VariableDefaultDescription
ANGARABASE_OPTIMIZER_PLANNING_TIMEOUT_MS0CBO planning budget in milliseconds (0 = disabled). On timeout the planner degrades to a greedy fallback plan instead of returning an error.
sql.optimizer.planning_timeout_ms0Settings surface alias for optimizer planning timeout; reflected in sys.settings when configured.

Vector execution knobs

VariableDefaultDescription
ANGARABASE_SQL_EXECUTION_MODEautoExecution mode for SELECT pipeline: auto (default, vector only when fully supported), force_vector (fail-closed if vector path is unavailable), force_row (always row engine). Legacy aliases vector and vector_auto remain accepted for compatibility.
ANGARABASE_VECTOR_BATCH_SIZE1024Vector batch size (1..1024), mostly useful for tests and diagnostics.
ANGARABASE_QUERY_MEMORY_LIMIT_MB256Per-query vector memory budget; exceeding the limit fails closed with SQLSTATE 53100 (no OOM fallback).

Parallel execution governance knobs

VariableDefaultDescription
ANGARABASE_PARALLEL_DOP_CAP_GLOBALCPU coresGlobal upper bound for SQL parallel workers.
ANGARABASE_PARALLEL_DOP_CAP_QUERYCPU coresPer-query upper bound for SQL parallel workers. Effective DOP is capped by both values.

Adaptive query processing knobs

VariableDefaultDescription
ANGARABASE_AQP_ENABLED1Global AQP switch for advisory feedback learning/apply.
ANGARABASE_AQP_MODEconservativeAQP mode (conservative / aggressive); conservative keeps correction hysteresis.
ANGARABASE_AQP_MIN_QUERY_TIME_MS100Minimum query runtime eligible for feedback observation.
ANGARABASE_AQP_LEARNING_RATE0.1EMA learning rate used for correction updates.
ANGARABASE_AQP_MAX_CORRECTION100.0Upper correction multiplier bound (guardrail against outliers).
ANGARABASE_AQP_VARIANCE_THRESHOLD10.0If variance exceeds threshold, correction entry is marked unstable and ignored.
ANGARABASE_AQP_CORRECTION_CACHE_MB64In-memory correction cache budget.
ANGARABASE_AQP_STORE_CAPACITY_MB1024Total bounded advisory store capacity; overflow evicts deterministic low-value entries.

OpenTelemetry tracing knobs

VariableDefaultDescription
ANGARABASE_OTEL_ENABLED0Enable OTel-style query span export (0 / 1).
ANGARABASE_OTEL_SAMPLE_RATE_PPM1000000Sampling in parts-per-million (0..1000000).
ANGARABASE_OTEL_EXPORTERstderrExport sink (stderr / file).
ANGARABASE_OTEL_ENDPOINT—Export target for file exporter (JSONL path).

See also Diagnostics for query performance analysis.

Authentication knobs

VariableDefaultDescription
ANGARABASE_AUTH_MODE—Auth mode contract (trust / scram / cert).

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

VariableDefaultDescription
ANGARABASE_SECURITY_BREAK_GLASS_MAX_TTL86400Max allowed break-glass TTL in seconds.

Audit knobs

VariableDefaultDescription
ANGARABASE_AUDIT_LOG_PATH—Path to append-only audit sink file (JSONL + chain-hash fields).
ANGARABASE_AUDIT_MAX_BYTES4194304 (4 MiB)Rotation threshold for audit sink.
ANGARABASE_AUDIT_DML_MODEoffAudit policy for DML (off / allowlist / denylist).
ANGARABASE_AUDIT_DML_ALLOWLIST—CSV schema.table list for audited DML (allowlist mode).
ANGARABASE_AUDIT_DML_DENYLIST—CSV schema.table list excluded from audit (denylist mode).
ANGARABASE_AUDIT_EXPORT_JSON_ENABLED0Enable JSON export worker.
ANGARABASE_AUDIT_EXPORT_SYSLOG_ENABLED0Enable syslog export worker.
ANGARABASE_AUDIT_EXPORT_RATE_LIMIT_RPS—Export rate limit in records/second (bounded).

AngaraIO v2 I/O Scheduler knobs

VariableDefaultDescription
ANGARABASE_IO_URING_QUEUE_DEPTH_LOWentries/4Low-priority I/O queue depth. Controls backpressure for non-critical operations. Clamped to 1–16384.
ANGARABASE_IO_URING_BATCH_MAX16Maximum I/O operations batched per scheduler round. Higher values improve throughput but increase latency. Clamped to 1–1024.

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

TDE (Transparent Data Encryption) knobs

VariableDefaultDescription
ANGARABASE_TDE_ENABLE0Enable TDE v0 for page/WAL at-rest encryption.
ANGARABASE_TDE_MASTER_KEY_HEX—Master key bytes in hex (64 chars; secret; required when TDE enabled).
ANGARABASE_TDE_MASTER_KEY_ID—Non-secret key identifier visible in sys.settings.
ANGARABASE_TDE_LAST_ROTATION_UNIX—Non-secret last-rotation timestamp visible in sys.settings.

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;

Диагностика

СимптомДействие
Сервер не стартует в trust-режимедобавьте --allow-insecure-no-auth
Несовпадение VERSION при стартекаталог данных инициализирован другой версией сервера — переинициализируйте или обновитесь
TDE fail-closed после restoreобеспечьте тот же ключ (ANGARABASE_TDE_MASTER_KEY_HEX)
Параметр не применилсяпроверьте приоритет: env переопределяет config; смотрите SELECT * FROM sys.settings (значения и источники)

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

См. также