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

Config Schema

Операторская сводка по поверхности конфигурации AngaraBase. Каноничный источник: этот runbook в angarabook/src/operations/.

Goal

Зафиксировать контракт конфига:

  • ключи и секции;
  • дефолты;
  • precedence и совместимость.

Core sections

  • [server]: addr (основной bind endpoint), host/port как deprecated.
  • [storage]: data_directory, transaction_log_directory (wal_directory как alias), io_backend_strict.
  • [logging]: log_level, log_directory.
  • [transaction_log]: backend, durability, fsync, checkpoint_target_lsn_lag_mb, checkpoint_min_interval_s.
  • [ops]: metrics_addr, admin_addr.
  • [security]: allow_insecure, dev_mode, TDE metadata fields.
  • [memory]: soft_limit_mb, hard_limit_mb, max_dataset_bytes.
  • [wal]: max_size_mb, performance and observability knobs.
  • [execution], [aqp], [diagnostics], [optimizer]: performance and observability knobs.

Config Strictness and Unknown Keys (RM-0.6.5.6)

Начиная с RM-0.6.5.6, наличие неизвестных ключей в именованных секциях ([server], [storage], [wal] и др.) приводит к FATAL ERROR при старте сервера. Это предотвращает опечатки в конфигурации, которые раньше могли игнорироваться.

  • При ошибке сервер выводит подсказку (Levenshtein suggestion) для наиболее похожего существующего ключа.

Пример ошибки при опечатке в ключе:

[ERROR] config: unknown key 'max_siz_mb' in section [wal]; did you mean 'max_size_mb'?

Диагностика: если сервер не стартует — проверить stderr / wrapper.log:

grep -i "unknown key\|config:" artifacts/golden_db/logs/wrapper.log | tail -20

WAL and Checkpoint Tuning (RM-0.6.5.8)

  • [wal] max_size_mb: Максимальный размер сегментов WAL. Применяется с RM-0.6.5.6 (ранее игнорировался).

    • Default: 512
    • ENV: ANGARABASE_WAL_MAX_SIZE_MB
    • Startup log: wal: max_size_mb=2048 MiB (source=config)

  • [transaction_log] checkpoint_target_lsn_lag_mb: Целевое отставание LSN для триггера чекпоинта.

    • Default: 256
    • ENV: ANGARABASE_CHECKPOINT_LSN_LAG_TRIGGER_MB
    • Startup log: checkpoint: lsn_lag_trigger_mb=256

  • [transaction_log] checkpoint_min_interval_s: Минимальный интервал между чекпоинтами в секундах.

    • Default: 300
    • ENV: ANGARABASE_CHECKPOINT_INTERVAL_MS (задается в миллисекундах для ENV)

  • [storage] io_backend_strict (default: false): Строгий режим проверки I/O бэкенда.

  • ANGARABASE_CHECKPOINT_BACKGROUND=true: Фоновый чекпоинт теперь включен по умолчанию.

Проверка применения max_size_mb при старте:

grep "wal: max_size_mb" artifacts/golden_db/logs/wrapper.log | tail -3
# Ожидаемый вывод: [INFO] wal: max_size_mb=512 MiB (source=config)

Memory Limits (RM-0.6.5.8)

Секция [memory] управляет потреблением оперативной памяти процессом сервера.

  • soft_limit_mb: Порог RSS (Resident Set Size) в MiB, при котором сервер начинает выдавать предупреждения (warn threshold).

    • Default: disabled (если не задан)
    • Поведение: при пересечении лимита инкрементируется метрика angarabase_memory_soft_limit_exceeded_total.
    • Пример: soft_limit_mb = 4096

  • hard_limit_mb: Жесткий предел RSS в MiB.

    • Default: disabled (если не задан)
    • Поведение: при превышении лимита сервер выполняет экстренный сброс данных (emergency flush) и завершается с exit(1).
    • Пример: hard_limit_mb = 8192

Index Maintenance and Durability (RM-0.6.5.8)

  • Index Durability: Начиная с RM-0.6.5.8, операция CREATE INDEX гарантирует долговечность (durability). После завершения команды индекс полностью синхронизирован и доступен после восстановления (recovery) даже в случае сбоя сразу после создания.

  • storage.max_index_pages_per_table (default: 65535): лимит страниц на один индекс.

  • storage.index_maintenance_budget_ms (default: 5000): бюджет времени на поддержку индексов в одной DML команде.

  • visibility_map.rebuild_max_pages_per_tick (default: 1024): темп фонового восстановления VM.

  • visibility_map.rebuild_io_budget_bytes (default: 10MB): I/O бюджет воркера VM.

Init behavior (--init)

angarabase-server --init использует effective settings и формирует bootstrap layout:

  • <root>/data
  • <root>/txlog
  • <root>/angarabase.conf (если не задан существующий config path)

Precedence

Правило приоритета:

  1. default
  2. config (angarabase.conf)
  3. environment override

Контракт: default -> config -> env.

Critical env surface (operator minimum)

  • ANGARABASE_TRANSACTION_LOG* (backend/durability/fsync)
  • ANGARABASE_METRICS_ADDR
  • ANGARABASE_TDE_*
  • ANGARABASE_TLS_*
  • ANGARABASE_MAX_DATASET_BYTES
  • ANGARABASE_AQP_*
  • ANGARABASE_GC_*

Backward compatibility policy

Breaking считается:

  • переименование ключа без alias периода;
  • unsafe изменение дефолта (например bind наружу);
  • смена семантики без migration notes.

Не-breaking:

  • новые ключи с безопасными дефолтами;
  • новые fail-closed проверки unsafe комбинаций с явным override.

Spill / Temp Storage (RM-0.6.4.2 — Spill to Disk)

Новые ENV knobs для управления spill-to-disk (Grace Hash Join, External Merge Sort, Set Ops) при превышении QueryMemoryBudget. Default disabled (безопасный fail-closed на OOM 53100).

Core spill knobs:

  • ANGARABASE_QUERY_SPILL_ENABLED=0 — включить spill path (set=1 for analytical workloads).
  • ANGARABASE_TEMP_MAX_BYTES_PER_QUERY (unlimited) — per-query soft quota.
  • ANGARABASE_TEMP_MAX_BYTES_TOTAL_* (SOFT/HARD) — global spill limits, fail-closed on hard.
  • ANGARABASE_TEMP_DIRECT_IO=0, ANGARABASE_TEMP_USE_O_TMPFILE=0, ANGARABASE_TEMP_OTMPFILE_DIRECT_FALLBACK=0 — io_uring + O_DIRECT + O_TMPFILE profile (production-like, kernel-managed cleanup on crash).
  • ANGARABASE_SPILL_HASH_JOIN_* (MAX_PARTITION_ROWS=8192, MAX_RECURSION_DEPTH=3, SKEW_THRESHOLD=75%, BLOOM_BITS=65536) — tuning recursion, skew handling, prefilter. Overflow → SQLSTATE 53400 graceful refusal.

Monitoring: see observability-metrics.md for angarabase_spill_*, angarabase_wal_* counters and sys.wait_events.

See RM-0.6.4.2 Surface Map and RFC-2026-492 for full contract. Recommended for HTAP/TPC-H with low ANGARABASE_QUERY_MEMORY_LIMIT_MB.

Дальше

  • Operations overview — где config-schema встроен в общий operator-материал.
  • Operational policies baseline — какие конфигурационные значения зафиксированы политикой.

GC Tuning (RM-0.6.6.11)

Columnar Manifest GC

  • ANGARABASE_COLUMNAR_MANIFEST_GC_INTERVAL_MS (config key: columnar.manifest_gc_interval_ms): Интервал между запусками фонового ManifestGC worker, который удаляет «ghost» ссылки на сегменты, отсутствующие в BlobStore.
    • Default: 60000 (60 секунд)
    • Рекомендуемый диапазон: 10000–300000
    • Мониторинг: angarabase_columnar_manifest_gc_removed_total — количество убранных ghost-ссылок; angarabase_catalog_snapshot_segments_total — текущий размер snapshot (индикатор роста манифеста).
    • Когда уменьшать: если angarabase_catalog_snapshot_segments_total стабильно растёт при неизменной нагрузке, а rate(angarabase_columnar_manifest_gc_removed_total[5m]) близко к нулю — GC не успевает; уменьши интервал.

Index GC Sweep Limit

  • ANGARABASE_INDEX_GC_MAX_SWEEP_PAGES (config key: storage.index_gc_max_sweep_pages): Максимальное число страниц B-tree, просматриваемых за один sweep IndexGC worker. Ограничивает I/O нагрузку GC на горячих индексах.
    • Default: 3000
    • Рекомендуемый диапазон: 500–10000
    • State-based trigger: если angarabase_index_gc_dead_fraction > 0.15, worker автоматически выполняет внеплановый sweep независимо от таймера.
    • Мониторинг: angarabase_index_gc_dead_fraction — текущая доля мёртвых записей (gauge, 0–1). Значение выше 0.20 требует attention.

Buffer Pool Config (RM-0.6.6.8)

В RM-0.6.6.8 были добавлены настройки для управления политикой вытеснения страниц и изоляции ресурсов для GC.

  • ANGARABASE_BUFFER_POOL_EVICTION: Выбор алгоритма вытеснения страниц.
    • Default: "2q"
    • Values: "2q", "3q" (включает полную политику 3Q с разделением на A1/Am очереди).
  • ANGARABASE_BUFFER_POOL_GC_RING_SIZE: Размер кольцевого буфера для операций GC (в страницах).
    • Default: 256
    • Описание: Позволяет изолировать I/O нагрузку от фоновой очистки индексов, предотвращая вымывание полезных данных из основного кэша.