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 (testing)

Goal

Start angarabased, connect via psql, execute basic DDL/DML, and verify that pgwire works.

Prerequisites

  • Linux x86_64
  • One of the installation options:
  • Rust toolchain (see rust-toolchain.toml) for a source build,
  • or the portable archive x86_64-unknown-linux-gnu (glibc >= 2.28).

Install from portable archive

mkdir -p /opt/angarabase
tar -xzf angarabase-0.6.3-x86_64-unknown-linux-gnu.tar.gz -C /opt/angarabase
/opt/angarabase/angarabase-0.6.3/bin/angarabase-server --version

If runtime glibc is below baseline (2.28), angarabase-server exits fail-closed with an explicit compatibility message.

Native package flow

For RPM/DEB deployments, service start is intentionally blocked before secure init:

angarabase-server --init /var/lib/angarabase --superuser admin --auth-mode scram --superuser-password-file /secure/path/pass.txt --require-auth
systemctl start angarabase

If you intentionally need trust bootstrap for isolated labs, it must be explicit:

angarabase-server --init /var/lib/angarabase --auth-mode trust --insecure-trust

Build

cargo build -p angarabase-server
cargo build -p angara-cli

Run server (local)

AngaraBase uses explicit instance initialization (--init) before regular startup.

Minimal path for testing (without manual config creation):

  1. Run the one-time initialization in the instance directory.
target/debug/angarabase-server --init /tmp/angarabase-instance --superuser angara_root --superuser-password 'change-me' --auth-mode scram

By default, this will create:

  • data/ at /tmp/angarabase-instance/data
  • txlog/ at /tmp/angarabase-instance/txlog
  • config angarabase.conf at /tmp/angarabase-instance/angarabase.conf
  1. Start the server:
target/debug/angarabase-server --config /tmp/angarabase-instance/angarabase.conf

In this scenario, the SCRAM bootstrap user angara_root is used. For local trust/no-auth mode, you can explicitly run with --allow-insecure-no-auth.

SecurityContext note:

  • In scram/cert modes, protected SQL execution requires session context.
  • Minimal setup for tenant-scoped workloads:
SET SESSION CONTEXT 'app.tenant_id' = 'public';

Alternative path (if you want to use an existing config):

  • --config <path> with --init is read as the input config if the file exists,
  • and written as the output config if the file does not exist.

Examples:

# init using an existing config (input)
target/debug/angarabase-server --config ./angarabase.conf --init

# init and write a new config (output; file must not exist)
target/debug/angarabase-server --config /tmp/angarabase.conf --init /tmp/angarabase-instance

A shortcut is allowed for local development:

target/debug/angarabase-server --config angarabase.conf --dev

--dev preserves the auto-init behavior only for dev/test scenarios.

Connect with psql

psql "host=127.0.0.1 port=5432 user=angara_root dbname=base password=change-me sslmode=disable"

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

  1. Stop the server (Ctrl+C).
  2. Start it again.
  3. Verify that the table is visible:
SELECT table_name FROM sys.tables WHERE table_name = 't';

Sys introspection (sys.*)

Examples of useful queries:

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. To enable it (locally/for tests):

export ANGARABASE_ALLOW_SQL_SHUTDOWN=1

You can then request a shutdown from psql:

SELECT sys.request_shutdown();

If something fails

What’s Next

Once the server has answered psql -h 127.0.0.1 and the basic SELECT has succeeded, logical next steps: