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

Configuration

Configure an AngaraBase instance for local testing or production: TOML config keys, data-directory conventions, and environment-variable overrides. Requires a built angarabase-server (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:9899" # Admin TCP API (remote backups via angara-cli --addr); empty = disabled

Transaction log (durability)

[transaction_log]
backend = "file_bin"   # durable binary WAL; required for MVCC crash recovery
durability = "strict"  # strict | relaxed | group_commit
fsync = true

The compiled-in backend default is noop (no durability, for ephemeral/test use). For any real instance set file_bin — MVCC crash recovery works only with it (see 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

Initialization workflow

Run --init before the first normal start:

angarabase-server --config-path /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:

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.

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

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).

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

SymptomAction
Server refuses to start in trust modeAdd --allow-insecure-no-auth.
VERSION mismatch at startupThe data directory was initialized by a different server version. Re-init or upgrade.
TDE fail-closed after restoreEnsure the same key material (ANGARABASE_TDE_MASTER_KEY_HEX) is available.
Parameter not appliedCheck precedence: env variables override config. Use SELECT * FROM sys.settings to see effective values and sources.

For unresolved issues see Known issues and Support.

See also