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

Quickstart: up and running in 5 minutes

Start angarabase-server, connect via psql, run basic DDL/DML, and verify that data and catalog survive a restart.

Prerequisites

  • Linux x86_64, glibc ≥ 2.28. The portable build checks this itself: on an older glibc, angarabase-server exits fail-closed with an explicit compatibility message.
  • One of: the portable archive x86_64-unknown-linux-gnu, or a source build (Rust toolchain — see rust-toolchain.toml).
  • A psql client (or any PostgreSQL-compatible client).

Install

Portable archive

VER=0.6.8
mkdir -p /opt/angarabase
tar -xzf angarabase-$VER-x86_64-unknown-linux-gnu.tar.gz -C /opt/angarabase
/opt/angarabase/angarabase-$VER/bin/angarabase-server --version

Build from source

cargo build --release -p angarabase-server -p angara-cli
# binary: target/release/angarabase-server

Step 1. Config

AngaraBase does not start from “magic” defaults — the data path and listen address are set explicitly. A minimal angarabase.conf:

[server]
addr = "127.0.0.1:5432"

[storage]
data_directory = "/var/lib/angarabase/data"
transaction_log_directory = "/var/lib/angarabase/txlog"

[logging]
log_level = "info"

The config path is passed via --config-path; without the flag, the server looks for /etc/angarabase/angarabase.conf. If a config is found but contains legacy keys, the server fails closed (exit 78) and lists them — there is no silent fall-through to defaults.

Step 2. Initialize the instance

A one-time initialization creates the catalog, data/, and txlog/ at the paths from the config. --init is a separate single-pass mode: the binary initializes the instance and exits with code 0.

angarabase-server --config-path ./angarabase.conf --init \
  --superuser angara_root \
  --superuser-password-file ./superuser.pw \
  --auth-mode scram --require-auth
  • --auth-mode scram — SCRAM-SHA-256 (the default; scram is an alias for the full name scram-sha-256).
  • --require-auth — fail-closed: init refuses if no superuser password is provided for a non-trust mode.
  • Password: --superuser-password-file <file> (recommended) or --superuser-password-env <VAR>. The inline form --superuser-password '...' exists too, but the password lands in your shell history.

Init prints instance_id, data_directory, txlog_directory. Re-running init on an already-initialized directory is fail-closed (already initialized).

⚠️ Insecure modes — explicit only. trust/no-auth (no authentication) is allowed only with an explicit --insecure-trust: --auth-mode trust --insecure-trust. Without that flag, init refuses. Use it only in isolated labs, never on a network.

Alternatively, without editing the config, override the instance root with flags; data/ and txlog/ are then created under that directory:

angarabase-server --config-path ./angarabase.conf --init \
  --init-root /var/lib/angarabase \
  --superuser angara_root --superuser-password-file ./superuser.pw \
  --auth-mode scram --require-auth

Step 3. Start the server

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

The server listens on 127.0.0.1:5432 (from the config). Binding to a non-loopback address without TLS/auth is also fail-closed: it requires an explicit --allow-insecure (or [security].allow_insecure = true). That flag is for controlled environments, not production.

⚠️ --allow-insecure / --allow-insecure-no-auth / --dev enable insecure presets (no TLS, no enforced auth). Use only in dev/test.

Step 4. Connect with psql

psql "host=127.0.0.1 port=5432 user=angara_root dbname=base password=<password> sslmode=disable"

base is the default logical database (schema public).

SecurityContext (scram / cert modes)

In scram/cert modes, protected SQL (RLS tables, tenant-scoped data) requires a session context — otherwise the security policy has nothing to bind to. Set the claim right after connecting:

SET SESSION CONTEXT 'app.tenant_id' = 'public';
-- equivalent short form:
SET app.tenant_id = 'public';

SET SESSION CONTEXT cannot be issued inside an open transaction (it returns an error). The value is read via current_setting('app.tenant_id') — RLS policies are built on it (see Authorization).

Smoke SQL

CREATE TABLE t (id INT PRIMARY KEY, v INT);
INSERT INTO t (id, v) VALUES (1, 10);
INSERT INTO t (id, v) VALUES (2, 20);
SELECT * FROM t ORDER BY id;

Restart check (DDL survives restart)

CREATE TABLE metadata (catalog) should survive a restart.

  1. Stop the server (Ctrl+C).
  2. Start it again: angarabase-server --config-path ./angarabase.conf.
  3. Verify the table is still there:
SELECT table_name FROM sys.tables WHERE table_name = 't';

Introspection via sys.*

SELECT * FROM sys.identity;
SELECT * FROM sys.health;
SELECT * FROM sys.settings WHERE name IN ('server.addr', 'storage.data_directory');
SELECT * FROM sys.tables;
SELECT * FROM sys.columns WHERE table_name = 't';

Optional: SQL shutdown (fail-closed)

By default, shutdown via SQL is disabled (knob ops.allow_sql_shutdown). Enable it locally/for tests:

export ANGARABASE_ALLOW_SQL_SHUTDOWN=1

You can then request a shutdown from psql:

SELECT sys.request_shutdown();

The operation passes an RBAC check and is written to the audit log; a user without privileges is denied.

If something fails

What’s next

Once the server answers psql -h 127.0.0.1 and a basic SELECT succeeds, the logical next steps: