Configuration

Goal

Configure a AngaraBase instance for local testing or production deployment using TOML config keys, data-directory conventions, and environment variable overrides.

Prerequisites

Built angarabase-server binary (see Quickstart)

Minimal config keys

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:9999" # reserved, not yet active

Transaction log (durability)

[transaction_log]
backend = "noop"
durability = "strict"
fsync = true

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
auto_shrink = true

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

Initialization workflow

Run --init before the first normal start:

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

Directories data_directory and transaction_log_directory must be writable.
When a valid logging.log_directory is set, the server writes angarabase-server.log.
--init creates all required data-directory artifacts (see below).

For local dev/test shortcuts see Quickstart.

Data directory artifacts

Inside storage.data_directory the server creates and maintains:

Artifact	Purpose
`VERSION`	Initialization marker (`format_version`, `min_server_version`); enforces fail-closed startup.
`base.adb`	On-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.

Environment variables

Environment variables override the corresponding config keys. When both are set, the env variable wins.

Precedence rule: default → config → env override

All parameters can be configured in angarabase.conf. Environment variables are intended for operational override without restart (for dynamic parameters) or for diagnostics. For permanent configuration, use the TOML config file.

Core server knobs

Variable	Default	Description
`ANGARABASE_SHUTDOWN_TIMEOUT_MS`	`1000`	Bounded graceful-shutdown timeout (ms).
`ANGARABASE_ALLOW_SQL_SHUTDOWN`	off	Allow shutdown trigger via `SELECT sys.request_shutdown()`.
`ANGARABASE_STORAGE_STRICT_STARTUP`	enabled	Storage verification on startup. Set `0`/`false`/`off` to disable.
`ANGARABASE_METRICS_ADDR`	—	Override for `[ops].metrics_addr`.
`ANGARABASE_SUPPORT_CONTACT`	`https://github.com/angarabase/angarabase/issues`	Support 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_TABLE`	`100000`	Default hard cap for `storage='memory'` tables when `max_rows` is omitted. Must be positive.

TLS knobs

Variable	Default	Description
`ANGARABASE_TLS_ENABLE`	off	Enable 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

Variable	Default	Description
`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

Variable	Default	Description
`ANGARABASE_WAL_VLF_ENABLE`	enabled	Enable VLF (Virtual Log Files) circular layout. Set `0` to disable and use linear WAL.
`ANGARABASE_WAL_MAX_SIZE_MB`	`512`	Maximum WAL file size in MB. Controls circular buffer size for VLF.
`ANGARABASE_WAL_VLF_SIZE_MB`	`32`	Individual VLF segment size in MB. Must be smaller than `WAL_MAX_SIZE_MB`.
`ANGARABASE_WAL_INIT_VLFS`	`2`	Initial number of VLF segments to allocate at startup.
`ANGARABASE_WAL_AUTO_SHRINK`	enabled	Automatically shrink unused VLF segments after checkpoint. Set `0` to disable.

Diagnostics / slow-query knobs

Variable	Default	Description
`ANGARABASE_LOG_MIN_DURATION_MS`	`-1` (disabled)	Slow-query log threshold in milliseconds.
`ANGARABASE_LOG_QUERY_TEXT`	`0`	Include 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

Variable	Default	Description
`ANGARABASE_OPTIMIZER_PLANNING_TIMEOUT_MS`	`0`	CBO 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_ms`	`0`	Settings surface alias for optimizer planning timeout; reflected in `sys.settings` when configured.

Vector execution knobs

Variable	Default	Description
`ANGARABASE_SQL_EXECUTION_MODE`	`auto`	Execution 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_SIZE`	`1024`	Vector batch size (`1..1024`), mostly useful for tests and diagnostics.
`ANGARABASE_QUERY_MEMORY_LIMIT_MB`	`256`	Per-query vector memory budget; exceeding the limit fails closed with SQLSTATE `53100` (no OOM fallback).

Parallel execution governance knobs

Variable	Default	Description
`ANGARABASE_PARALLEL_DOP_CAP_GLOBAL`	CPU cores	Global upper bound for SQL parallel workers.
`ANGARABASE_PARALLEL_DOP_CAP_QUERY`	CPU cores	Per-query upper bound for SQL parallel workers. Effective DOP is capped by both values.

Adaptive query processing knobs

Variable	Default	Description
`ANGARABASE_AQP_ENABLED`	`1`	Global AQP switch for advisory feedback learning/apply.
`ANGARABASE_AQP_MODE`	`conservative`	AQP mode (`conservative` / `aggressive`); conservative keeps correction hysteresis.
`ANGARABASE_AQP_MIN_QUERY_TIME_MS`	`100`	Minimum query runtime eligible for feedback observation.
`ANGARABASE_AQP_LEARNING_RATE`	`0.1`	EMA learning rate used for correction updates.
`ANGARABASE_AQP_MAX_CORRECTION`	`100.0`	Upper correction multiplier bound (guardrail against outliers).
`ANGARABASE_AQP_VARIANCE_THRESHOLD`	`10.0`	If variance exceeds threshold, correction entry is marked unstable and ignored.
`ANGARABASE_AQP_CORRECTION_CACHE_MB`	`64`	In-memory correction cache budget.
`ANGARABASE_AQP_STORE_CAPACITY_MB`	`1024`	Total bounded advisory store capacity; overflow evicts deterministic low-value entries.

OpenTelemetry tracing knobs

Variable	Default	Description
`ANGARABASE_OTEL_ENABLED`	`0`	Enable OTel-style query span export (`0` / `1`).
`ANGARABASE_OTEL_SAMPLE_RATE_PPM`	`1000000`	Sampling in parts-per-million (`0..1000000`).
`ANGARABASE_OTEL_EXPORTER`	`stderr`	Export sink (`stderr` / `file`).
`ANGARABASE_OTEL_ENDPOINT`	—	Export target for `file` exporter (JSONL path).

See also Diagnostics for query performance analysis.

Authentication knobs

Variable	Default	Description
`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

Variable	Default	Description
`ANGARABASE_SECURITY_BREAK_GLASS_MAX_TTL`	`86400`	Max allowed break-glass TTL in seconds.

Audit knobs

Variable	Default	Description
`ANGARABASE_AUDIT_LOG_PATH`	—	Path to append-only audit sink file (JSONL + chain-hash fields).
`ANGARABASE_AUDIT_MAX_BYTES`	`4194304` (4 MiB)	Rotation threshold for audit sink.
`ANGARABASE_AUDIT_DML_MODE`	`off`	Audit 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_ENABLED`	`0`	Enable JSON export worker.
`ANGARABASE_AUDIT_EXPORT_SYSLOG_ENABLED`	`0`	Enable syslog export worker.
`ANGARABASE_AUDIT_EXPORT_RATE_LIMIT_RPS`	—	Export rate limit in records/second (bounded).

AngaraIO v2 I/O Scheduler knobs

Variable	Default	Description
`ANGARABASE_IO_URING_QUEUE_DEPTH_LOW`	`entries/4`	Low-priority I/O queue depth. Controls backpressure for non-critical operations. Clamped to 1–16384.
`ANGARABASE_IO_URING_BATCH_MAX`	`16`	Maximum 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

Variable	Default	Description
`ANGARABASE_TDE_ENABLE`	`0`	Enable 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).

Expected result

After a successful --init and start:

curl -sS http://127.0.0.1:9898/health/ready # port matches [ops].metrics_addr

Returns {"status":"ready"}. Effective configuration is visible via:

SELECT * FROM sys.settings;

Troubleshooting

Symptom	Action
Server refuses to start in trust mode	Add `--allow-insecure-no-auth`.
`VERSION` mismatch at startup	The data directory was initialized by a different server version. Re-init or upgrade.
TDE fail-closed after restore	Ensure the same key material (`ANGARABASE_TDE_MASTER_KEY_HEX`) is available.
Parameter not applied	Check precedence: env variables override config. Use `SELECT * FROM sys.settings` to see effective values and sources.

For unresolved issues see Known issues and Support.

AngaraBook