AaronDB

“Simplicity is not about making things easy. It is about untangling complexity.” - Rich Hickey

AaronDB is a BEAM-native temporal Datalog engine written in Gleam. Its strongest current shape is a fact-oriented database core built around a transactor actor, immutable-style state transitions, in-memory indexes, and a custom query engine.

This repository also contains experimental distributed, search, MCP, cognitive, and CMS layers. Those subsystems are not all at the same maturity level. See docs/feature_maturity.md and docs/project_boundaries.md before adopting non-core features.

Core Model

1. Facts, not objects: data is represented as datoms.
2. Actor-owned writes: a transactor process serializes state transitions.
3. Query over values: reads execute against database state snapshots.
4. Storage is pluggable: the engine is decoupled from persistence adapters.

What Is Solid Today

• In-memory transactional core
• Datom model with transaction and valid-time fields
• Query DSL and interpreted query execution
• Pull, history, diff, and speculative state evaluation
• Constraints for uniqueness, cardinality, predicates, and composites
• Broad automated test coverage

Maturity Snapshot

Installation

Add aarondb to your gleam.toml:

[dependencies]
aarondb = "2.4.5"

Why 2.4.5 Is Better

AaronDB 2.4.5 verifies the final autonomous GitHub release path.

• CI and release workflows now target the current Gleam toolchain, install rebar3, run on OTP 27, and declare explicit release permissions.
• Tag-triggered releases can publish automatically to Hex.pm when HEX_API_KEY is present.
• The package remains green: 169 tests pass with zero warnings.

Basic Usage

Create an in-memory database:

import aarondb

let db = aarondb.new()

Transact facts:

import aarondb
import aarondb/fact.{EntityId, Str, Uid}

let assert Ok(_state) = aarondb.transact(db, [
  #(Uid(EntityId(101)), "user/name", Str("Alice")),
  #(Uid(EntityId(101)), "user/role", Str("Admin")),
])

Query with the DSL:

import aarondb
import aarondb/q

let query =
  q.select(["name"])
  |> q.where(q.v("e"), "user/role", q.s("Admin"))
  |> q.where(q.v("e"), "user/name", q.v("name"))
  |> q.to_clauses()

let results = aarondb.query(db, query)

Use temporal and pull APIs:

import aarondb
import aarondb/fact

let history = aarondb.history(db, fact.Uid(fact.EntityId(101)))
let entity = aarondb.pull(db, fact.Uid(fact.EntityId(101)), aarondb.pull_all())

Start a sharded cluster when you explicitly want the experimental distributed layer:

import aarondb/sharded

let assert Ok(cluster) = sharded.start_sharded("cluster", 4, None)

Documentation

• Architecture
• Feature Maturity
• Project Boundaries
• Query DSL
• Supervision
• Distributed Guide

Current Recommendation

Treat AaronDB first as a temporal Datalog engine with a strong in-memory core. Adopt peripheral layers only with explicit evaluation of their maturity and operational trade-offs.