AngaraBase

Getting Started

Choose your entry point based on your role:

Key Features

PostgreSQL Compatibility Without Surprises

• Standard pgwire protocol: psql, JDBC, psycopg, node-postgres, pgx, Npgsql work just like with standard PostgreSQL.
• Contractual SQL subset: what is supported is supported fully; what is not supported returns an explicit SQLSTATE (0A000 etc.) instead of a silent bypass.
• Pinned compatibility tests (compat suite) as proof, rather than a “compatibility percentage”.

Read more: SQL compatibility overview.

Modern Engine: MVCC via UNDO-log, Not via Bloat

Unlike PostgreSQL, AngaraBase stores historical row versions in a separate UNDO-log (like Oracle/InnoDB), rather than in the table itself. As a result:

• heap pages contain only current row versions → less bloat;
• VACUUM in the traditional sense is not needed — old versions are cleaned up by the background AngaraGC according to a strict contract;
• visibility for transactions is determined deterministically by snapshot.

Read more: Transactions and MVCC.

Pluggable Storage From Day One

• Row-store (baseline) — for OLTP.
• AngaraMemory — in-memory tables with three durability tiers (none / logged / snapshotted) and hard row-cap.
• AngaraColumn — columnar storage for analytics (in roadmap; HTAP direction).

Storage engine is selected during CREATE TABLE ... WITH (storage='memory'|'row'|...).

Read more: Storage engine.

Cost-based Optimizer and Vectorized Execution

• AngaraPlan — CBO with robust planning, resilient to estimation errors.
• AngaraStat — statistics: HLL for NDV, equi-height histograms, MCV (reservoir sampling).
• AngaraFlow — streaming execution (Volcano).
• AngaraVector — vectorized path for scan/filter/project/join/aggregate; modes auto / force_vector / force_row. EXPLAIN explicitly shows VectorHashJoin, VectorAgg, etc.
• AngaraParallel — partitioned parallel join, DOP-caps (ANGARABASE_PARALLEL_DOP_CAP_*).

Read more: Query processing.

Multi-layered Security With Explicit Contracts

Security is built into the core, not “bolted on” as an afterthought. Six layers of protection, each with its own contract:

1. Transport and identity — TLS, SCRAM, cert authentication.
2. RBAC — who is allowed at all.
3. RLS v1 — which rows are visible and mutable.
4. Break-glass — the only way to bypass RLS (even SUPERUSER doesn’t have it), always with a REASON, TTL, and audit.
5. Audit chain — append-only, tamper-evident (SHA-256 chain).
6. TDE — encryption of pages, WAL, and audit-sink; fail-closed without a key.

Read more: Security model.

Operations Built for Predictability

• Per-database backup and restore (cold + online/PITR baseline).
• Clear diagnostics: EXPLAIN/EXPLAIN ANALYZE, sys.* views (sys.identity, sys.health, sys.settings, sys.tables, sys.column_stats, angara_stat_activity, angara_stat_statements).
• Structured logging, OpenTelemetry-style spans, USDT/eBPF probes.
• Prometheus metrics: angara_* named subsystems are visible in logs, metrics, and EXPLAIN.
• Native RPM/DEB packages, init-first service start fence, systemd units.

Read more: Operations runbooks.

Project Principles (Explicit Stance)

Full declaration: Project principles.

Documentation Sections

Tutorials

• What is AngaraBase
• AngaraBase Architecture
• Quickstart

Concepts (Explanation)

• Storage Engine — row-store, pages, slotted pages, pluggable storage
• Transactions and MVCC — UNDO-log MVCC, isolation, GC
• Indexes — AngaraTree (B+tree, BRIN), IndexStore
• Query Processing — AngaraPlan, AngaraStat, AngaraFlow, AngaraVector
• Catalog and Metadata — SysCatalog and sys.* views
• Instance Lifecycle — init, startup, recovery, shutdown

SQL Reference

• Compatibility Overview — policy, SQLSTATE codes, vector execution
• Data Types — supported types, casting, NULL
• DDL — CREATE/ALTER/DROP, indexes, constraints
• DML — INSERT, UPDATE, DELETE, mutation policies
• Queries — CTE, JOIN, aggregates, ORDER BY
• Partitioning — RANGE/LIST partitioning, routing, pruning

Security (How-to)

• Security Model
• Authentication
• Authorization (RBAC + RLS)
• Audit
• Encryption (TDE + client-side)
• Break-glass
• Hardening Runbook
• GOST Compliance

Operations (How-to)

• Installation — portable archive, RPM/DEB, source build
• Configuration — TOML, env, sys.settings
• Backup and Restore — cold + online/PITR
• Crash Recovery — host migration, WAL replay
• Version Upgrade
• Monitoring — Prometheus, Grafana, health probes
• Diagnostics — EXPLAIN, slow log, sys.*
• Logging, Tracing, USDT/eBPF probes
• GC auto-tuning
• Error debug runbook (10 minutes)
• GOST crypto setup
• Verify release artifacts

Operator deep-dives — runbooks (Reference)

• Operations overview
• Runbooks index
• Troubleshooting guide
• Disaster recovery playbook
• Performance tuning guide
• MVCC and GC operator minimum
• Diagnostics bundle runbook
• Security operations baseline
• Upgrade and migration
• Backup and restore (operator-level)
• Configuration schema reference
• Observability metrics checklist
• jemalloc heap profiling runbook
• Parallel runtime observability runbook
• Replication v2 operations guide
• Operational policies baseline
• Client compatibility baseline (operator)
• Testing and validation baseline
• Golden dataset management
• CI reproducibility contract
• Known issues baseline (operator)

Architecture (Reference)

• Architecture overview
• Layering and Boundaries

Reference

• Known Issues and SQLSTATE
• Glossary and Named Subsystems
• System Views sys.*
• Client Compatibility
• Support and Bug Report Artifact Collection
• Generated reference (auto-generated registries)

Changelog

• AngaraBook changelog (highlights) — concise change feed from a user perspective.

Community and Contribution

We welcome community contributors:

• Found a bug or regression? Gather artifacts according to the Support flow and open an issue.
• Want to change behavior? Propose an RFC via the project’s development process (internal loop).
• Want to help with documentation? AngaraBook is documentation-as-code in the same repository. Formatting rules: see the internal WRITING_RULES.md next to the book.
• Want to track development? Follow the changelog and release notes.

About the Documentation

AngaraBook is built on the principles of Diátaxis:

• Tutorials — learning through action, for new users.
• How-to guides (Security / Operations) — recipes for specific tasks.
• Reference (SQL / Architecture) — exact description of behavior.
• Explanation (Concepts) — why things are designed the way they are.

Quality Guarantees:

• Documentation is code: edited in the same repository, passes the same CI as the engine.
• Any claimed SQL/ops behavior is verified by pinned tests or explicitly marked as a roadmap feature.
• Anti-drift: command versions, configuration keys, and SQLSTATE codes are checked automatically.
• Public build passes a security gate: internal processes and confidential links do not make it into the public portal.

If you notice a discrepancy between the documentation and actual behavior — this is a documentation bug; please report it.

AngaraBase v0.6.x · Linux x86_64/aarch64 · glibc >= 2.28