AuraDB

Production-supported single-node database for typed records, documents, exact vectors, BM25-ranked text, and hybrid search.

AuraDB is a Rust-native, single-node database server. One transactional store holds records that are simultaneously typed rows, nested documents, graph nodes, and embedding holders — so an AI application can keep relational state, document fields, relationships, exact vectors, and ranked text search in one place instead of stitching together four systems. It speaks the Aura Wire Protocol over TCP, persists and recovers data locally, and ships with auth, TLS, backups, observability, and operator runbooks.

The matching client is Aura Connector, a typed async Python connector. AuraDB v1.5.1 pairs with Aura Connector v0.9.x.

docker run --rm -p 7171:7171 -v auradb-data:/data ghcr.io/ohswedd/auradb:1.5.1

Support status

Mode / capability	Status	Production use
Single-node with auth + TLS + backups + monitoring	Stable	Yes (recommended)
Backup / restore, upgrade from v0.x	Stable	Yes
Exact vector search, tokenized full-text	Stable	Yes
BM25 ranked full-text, hybrid text+vector search	Stable	Yes
Aggregations, terms facets, cooperative query timeouts	Stable (v1.2.0)	Yes
GROUP BY aggregations, EXPLAIN ANALYZE query-profile fields	Stable (v1.3.0)	Yes
Single-node production drill harness, search relevance evaluation (auradb search eval)	Stable (v1.4.0)	Yes (operability + search-quality tooling)
Live search analyzers + opt-in snippets/highlights (query_analyzers, search_snippets)	Stable (v1.5.0)	Yes (search-quality tooling)
Aura Connector 0.9.x, AWP 1, storage format v2	Stable / frozen for v1	Yes
Static multi-node cluster (Raft)	HA candidate preview	No (not production HA)
Approximate (HNSW) vector search	Opt-in preview (v1.2.0)	No (not production ANN)

Single-node mode is the recommended production mode. Multi-node static clustering is an HA candidate preview with strong release-candidate evidence — it is not production HA, has no production automatic failover, and is off by default. The authoritative boundaries are in docs/SUPPORT_POLICY.md, docs/COMPATIBILITY.md, and docs/HA_RELEASE_CANDIDATE.md.

Install and run

# Docker (development image; binds all interfaces with --allow-insecure-bind).
docker run --rm -p 7171:7171 -v auradb-data:/data ghcr.io/ohswedd/auradb:1.5.1

# From source (stable Rust 1.85+). The server and CLI is one binary: target/release/auradb.
git clone https://github.com/Ohswedd/auradb.git && cd auradb
cargo build --release
./target/release/auradb init   --data-dir .local/auradb --config AuraDB.toml
./target/release/auradb server --data-dir .local/auradb --bind 127.0.0.1 --port 7171
./target/release/auradb status --addr 127.0.0.1:7171     # in another shell

Binding loopback (127.0.0.1) is local developer mode and may leave auth disabled. Binding a non-loopback address with auth disabled is rejected at startup unless you explicitly opt in. For a real deployment use the secure Compose file (auth + TLS, non-root, read-only root filesystem, no committed secret): see docs/DEPLOYMENT.md.

docker compose -f docker-compose.secure.yml config   # validate the secure stack

Connect

Aura Connector talks to AuraDB over AWP 1, including auth and TLS. AuraDB v1.5.1 is paired with Aura Connector v0.9.x (analyzer-aware search, snippet request/result helpers, connection profiles, search-eval report parsing helpers, capability require/describe helpers); v0.8.x and v0.7.x remain supported (backward compatible) for the existing feature set, which is unchanged at the wire-protocol level.

python -m pip install "aura-connector>=0.6,<0.7"

from aura import connect
from aura.config import TokenAuth, TLSConfig

async with connect(
    "auradbs://db.example.com:7171/app",
    models=[Doc],
    auth=TokenAuth("your-secret"),
    tls=TLSConfig(enabled=True, ca_cert_path="/etc/aura/ca.pem"),
) as client:
    await client.insert(Doc(id=1, title="Refunds", body="...", embedding=[0.1, 0.2, 0.3]))

The Rust conformance client in crates/auradb-conformance and a Python harness in tests/conformance/python exercise every capability over the wire. Compatibility is documented in docs/AURA_CONNECTOR_COMPATIBILITY.md and docs/COMPATIBILITY.md.

Data model

A record belongs to a typed collection defined by a schema and can carry, at the same time:

• Typed scalar fields — uuid, string, int, float, bool, timestamp, bytes, with primary keys, unique and secondary indexes, and validation.
• Document fields — JSON-like nested objects/arrays, filterable and orderable by dotted path, with optional document-path equality indexes (docs/DOCUMENTS.md).
• Relationships — forward links hydrated through query include, with referential consistency on delete (docs/RELATIONSHIPS.md).
• Vectors — fixed-dimension embeddings stored inline, validated by dimension (docs/VECTORS.md).

Records are addressed by a stable logical id; physical storage offsets are never exposed as durable identity.

Query and search

Reads route through a cost-based planner that uses persisted statistics to pick the most selective index or a full scan, with EXPLAIN and EXPLAIN ANALYZE. The Query IR supports point reads, filters (=, !=, <, <=, >, >=, in, contains, contains_text, AND/OR/NOT, document paths), ordering, limit/offset, projection, count, exists, insert/bulk/update/delete/upsert, relationship includes, and a migration impact estimate.

Search and ranking (docs/SEARCH_AND_RANKING.md) adds:

• BM25 ranked full-text (text_search) — Okapi BM25 over a full-text indexed field, with tunable k1/b.
• Exact vector search (vector) — exact nearest-neighbour by cosine, euclidean, or dot_product. This is the default and the correctness baseline. Approximate (HNSW) vector search is available as an opt-in preview (v1.2.0) — the graph is never persisted; it rebuilds in memory from the exact vectors on use, not production ANN. v1.3.0 adds durable preview lifecycle metadata, an ann_fallback (exact/error) policy, a vector_mode field in EXPLAIN, and the auradb vector eval recall/latency harness.
• Hybrid text + vector (hybrid) — BM25 and vector signals fused by weighted sum or reciprocal-rank fusion.
• Aggregations (aggregate) — count/min/max/avg metrics and terms facets, plus GROUP BY over a single scalar field (v1.3.0), all over one matched set (filtered scan or BM25 search-candidate scope).

# Inspect a ranked query's plan (and measured metrics with --analyze).
auradb search explain --input examples/search_bm25.json
auradb search explain --input examples/search_hybrid.json --analyze

# Measure ranked-retrieval relevance (MRR@k / NDCG@k / Recall@k) on a committed
# relevance fixture — bm25, vector_exact, or hybrid. Results are fixture-specific
# regression signals, not universal benchmarks (use a fresh --data-dir).
auradb search eval \
  --data-dir .local/search-eval \
  --corpus fixtures/relevance/small_corpus.jsonl \
  --queries fixtures/relevance/small_queries.jsonl \
  --qrels fixtures/relevance/small_qrels.jsonl \
  --mode bm25 --k 10 --json

The relevance dataset format, BM25 k1/b tuning, and hybrid weight calibration are documented in docs/SEARCH_AND_RANKING.md and fixtures/relevance/README.md.

The legacy contains_text boolean predicate and term-frequency ranking are unchanged (docs/FULL_TEXT.md). Unsupported operations return a structured capability error.

Storage and transactions

Storage is an append-only, CRC32C-checksummed segment log with a manifest, using MVCC version chains (storage format v2): each record id maps to an ordered chain of commit-timestamped versions, and a delete is a tombstone version. On open the engine replays segments to rebuild version chains and indexes; a torn tail is detected by checksum and truncated. Transactions pin a read timestamp at begin, overlay their own staged writes, and commit with optimistic first-committer-wins conflict detection. AuraDB implements single-node snapshot isolation — not serializable isolation. See docs/STORAGE_ENGINE.md and docs/TRANSACTIONS.md.

Operations

• Security. Enforced static-token authentication (Argon2id-hashed, constant-time) and server-terminated TLS with optional mutual TLS (rustls), both fail-closed. In-place token rotation with auradb auth rotate-token. #![forbid(unsafe_code)] across every crate. Not implemented: RBAC, field-level encryption, encryption at rest, audit logging. See docs/SECURITY.md and SECURITY.md.
• Backup / restore / upgrade. auradb dump → auradb backup verify → auradb restore → auradb check; older data directories migrate to storage format v2 transparently on first open. See docs/OPERATIONS.md and docs/UPGRADING.md.
• Health. auradb doctor and auradb status print redacted health (--json); auradb check verifies on-disk index consistency.
• Observability. A metrics registry exports counters, gauges, and latency histograms as JSON and Prometheus text; structured tracing and health/readiness surfaces are built in, with no external collector required (docs/OBSERVABILITY.md).
• Runbooks. Single-node production guidance and operator procedures are in docs/PRODUCTION_READINESS.md and docs/RUNBOOKS.md.

A full command reference is in docs/CLI.md.

Multi-node preview

AuraDB can form a static, cross-process cluster that elects a leader and replicates writes through Raft over an authenticated, frame-checked peer transport. The preview is off by default and gated behind two explicit [cluster] opt-ins:

[cluster]
enabled = true
experimental_multi_node = true

What works: leader election, majority-commit replication, leader-only writes (followers return a structured not_leader error with a leader hint), follower catch-up, snapshot install, and live tooling (auradb cluster leader|wait-leader|wait-ready, auradb status --json). The validated path is the three-node loopback example in examples/cluster.

What remains preview: this is for local testing and early validation only. It is not production HA. Not provided: production automatic failover, dynamic membership, linearizable follower reads, distributed transactions, sharding, and multi-region. The evidence required before any production HA claim is tracked in docs/HA_RELEASE_CANDIDATE.md; see also docs/CLUSTERING.md and docs/CLUSTER_TROUBLESHOOTING.md.

Not supported

AuraDB is deliberately honest about its boundaries. The following are not implemented and not claimed: production HA, production automatic failover, production cluster readiness, dynamic membership, distributed transactions, linearizable follower reads, sharding, multi-region; production approximate (ANN/HNSW) vector search (an opt-in HNSW preview ships in v1.2.0 — in-memory/rebuilt, not persisted/incremental and not production ANN); serializable isolation; RBAC, field-level encryption, encryption at rest, and audit logging. Planned directions are in docs/ROADMAP.md.

Documentation

Getting started — Deployment · CLI · Configuration · Architecture · Design decisions

Query & search — Query engine · Search & ranking · Full-text · Vectors · Documents · Relationships · Cursors · Indexing · Storage engine · Transactions

Operations — Production readiness · Operations · Runbooks · Observability · Upgrading · Benchmarks

Security — Security policy · Security model

Compatibility — Compatibility matrix · Support policy · Connector compatibility · Protocol

Multi-node preview — HA candidate · Clustering · Raft · Replication · Cluster troubleshooting

Release & contributing — Changelog · Roadmap · Release process · Testing · Conformance · Contributing · Code of Conduct

Testing

cargo test --workspace --all-features

Tests span unit, integration over real TCP, backup/restore, the v1-to-v2 MVCC upgrade, snapshot isolation and version GC, planner and EXPLAIN ANALYZE, ranked and hybrid search, deterministic chaos/recovery and corruption drills, multi-node replication, and conformance. See docs/TESTING.md.

License

Licensed under the Apache License, Version 2.0.