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

Operator summary of the AngaraBase configuration surface. Canonical source: this runbook in angarabook/src/operations/.

Goal

Pin the config contract:

  • keys and sections;
  • defaults;
  • precedence and compatibility.

Core sections

  • [server]: addr (main bind endpoint), host/port as deprecated.
  • [storage]: data_directory, transaction_log_directory (wal_directory as 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)

Starting with RM-0.6.5.6, unknown keys in named sections ([server], [storage], [wal], etc.) cause FATAL ERROR at server startup. This prevents typos in configuration that could previously be ignored.

  • On error, the server prints a hint (Levenshtein suggestion) for the closest existing key.

Example typo error in a key:

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

Diagnostics: if the server does not start, check 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: Maximum WAL segment size. Applied since RM-0.6.5.6 (previously ignored).

    • 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: Target LSN lag for checkpoint trigger.

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

  • [transaction_log] checkpoint_min_interval_s: Minimum interval between checkpoints in seconds.

    • Default: 300
    • ENV: ANGARABASE_CHECKPOINT_INTERVAL_MS (specified in milliseconds for ENV)

  • [storage] io_backend_strict (default: false): Strict I/O backend verification mode.

  • ANGARABASE_CHECKPOINT_BACKGROUND=true: Background checkpoint is now enabled by default.

Verify max_size_mb application at startup:

grep "wal: max_size_mb" artifacts/golden_db/logs/wrapper.log | tail -3
# Expected output: [INFO] wal: max_size_mb=512 MiB (source=config)

Memory Limits (RM-0.6.5.8)

The [memory] section controls server process RAM consumption.

  • soft_limit_mb: RSS (Resident Set Size) threshold in MiB at which the server starts emitting warnings.

    • Default: disabled (if not set)
    • Behavior: when the limit is crossed, angarabase_memory_soft_limit_exceeded_total is incremented.
    • Example: soft_limit_mb = 4096

  • hard_limit_mb: Hard RSS limit in MiB.

    • Default: disabled (if not set)
    • Behavior: when the limit is exceeded, the server performs an emergency flush and exits with exit(1).
    • Example: hard_limit_mb = 8192

Index Maintenance and Durability (RM-0.6.5.8)

  • Index Durability: Starting with RM-0.6.5.8, CREATE INDEX guarantees durability. After the command completes, the index is fully synchronized and available after recovery even if a crash happens immediately after creation.

  • storage.max_index_pages_per_table (default: 65535): page limit per index.

  • storage.index_maintenance_budget_ms (default: 5000): time budget for index maintenance in one DML command.

  • visibility_map.rebuild_max_pages_per_tick (default: 1024): background VM rebuild rate.

  • visibility_map.rebuild_io_budget_bytes (default: 10MB): I/O budget of the VM worker.

Init behavior (--init)

angarabase-server --init uses effective settings and creates the bootstrap layout:

  • <root>/data
  • <root>/txlog
  • <root>/angarabase.conf (if an existing config path is not set)

Precedence

Precedence rule:

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

Contract: 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 includes:

  • renaming a key without an alias period;
  • unsafe default change (for example, binding externally);
  • semantic change without migration notes.

Non-breaking:

  • new keys with safe defaults;
  • new fail-closed checks for unsafe combinations with explicit override.

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

New ENV knobs control spill-to-disk (Grace Hash Join, External Merge Sort, Set Ops) when QueryMemoryBudget is exceeded. Default disabled (safe fail-closed on OOM 53100).

Core spill knobs:

  • ANGARABASE_QUERY_SPILL_ENABLED=0 — enable 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.

Next