persiadb

Persia DB

An embedded, single-file search database, written in Rust.
Open a file. Index documents. Ranked results, with relaxation on by default.

Docs  ·  Getting started  ·  SPEC  ·  Roadmap  ·  Progress

Pre-alpha. The 2026-10-27 snapshot in PROGRESS.md is 210 of 451 MVP leaves (47%). Post-MVP work is 0 of 151 and sits outside that percentage. Format 1.0 is unstable until the v1.0 release (SPEC §15). When this file and PROGRESS.md disagree, PROGRESS.md wins.

The docs homepage plays this poster from persia-hero.webm and persia-hero.mp4.

persia does not export Db yet. What you can call today is the segment library, the text analyzers, the single-file container, and a small CLI. Query, ranking, and relaxation are specified and not implemented.

Why Persia DB

The product is a search database you link, the way you link SQLite. The design is SPEC §1. The rows below say what that buys, and how far the tree has gotten.

Out of scope for v1, in the SPEC: SQL, joins, vector search, more than one writer on a shard, and encryption inside the file. Encryption at rest is v1.2. Geo and the enterprise work are v3.0. See Status.

Comparison

Product shape, from SPEC §1, the comparison guide, and each project's own documentation.

For a search feature in production today, use one of the released tools. Persia DB is the design in the SPEC — an embedded Rust API, one local file, the same segment bytes in object storage, relaxation on by default — and the implementation of the layers under that API.

Quickstart

The crates are unpublished (publish = false, version 0.0.0). There is no crates.io release and no cargo add persia.

Build a segment and look up a term

This is the highest API the engine exports. It writes one immutable segment in memory and reads it back. Opening app.persia, ranking, and relaxation are the planned API below. The calls are the doctest on Segment, wrapped in main.

[dependencies]
persia-engine = { git = "https://github.com/tomiok/persiaDB" }
persia-analysis = { git = "https://github.com/tomiok/persiaDB" }
persia-format = { git = "https://github.com/tomiok/persiaDB" }

use persia_analysis::AnalyzerRegistry;
use persia_engine::document::{Document, Value};
use persia_engine::schema::{FieldKind, SchemaBuilder, TextOptions};
use persia_engine::segment::{Segment, SegmentBuilder, SegmentMeta, SegmentWriter};
use persia_format::ByteSource;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let schema = SchemaBuilder::new("notes")
        .field("body", FieldKind::Text(TextOptions::default()))
        .build()?;
    let body = schema.field("body").map(|f| f.id()).ok_or("no field")?;
    let mut builder = SegmentBuilder::new(&schema, &AnalyzerRegistry::builtin())?;
    builder.add(&Document::new("n1").with(body, Value::String("Hello, world".into())))?;

    let meta = SegmentMeta {
        segment_id: 7,
        created_at: 0,
        merge_generation: 0,
    };
    let bytes = SegmentWriter::new(&builder, meta).finish()?;

    // The default text analyzer is `standard`: "Hello" is indexed as "hello".
    let segment = Segment::open(ByteSource::new(bytes.into()), &schema)?;
    assert_eq!((segment.segment_id(), segment.doc_count()), (7, 1));
    let info = segment.terms(body)?.get(b"hello")?.ok_or("no term")?;
    assert_eq!(info.df(), 1);
    assert_eq!(
        segment.document(0)?.get(body),
        Some(&Value::String("Hello, world".into()))
    );
    Ok(())
}

Field types on a CollectionSchema are text, keyword, i64, f64, bool, datetime, and stored. A schema is valid only after SchemaBuilder::build or CollectionSchema::from_json.

Container::create("app.persia") and Container::open in persia-storage create and recover the single-file container (header, two superblock slots, checksummed frames). That file is the container. It is not yet an index of documents.

CLI

git clone https://github.com/tomiok/persiaDB.git
cd persiaDB
cargo run -p persia-cli -- inspect segment \
  tests/fixtures/segment/v1.0/basic.pseg \
  --schema tests/fixtures/segment/v1.0/basic.schema.json \
  --verify

The binary is persia. These subcommands exist:

The golden segment above is format 1.0 and holds 300 documents (doc_count in the inspect output; see crates/persia-cli/tests/segment.rs).

Planned (ROADMAP 10.4): compact, stats, import (JSONL), search, and bench.

Planned embedded API

Planned (M10). This block does not compile. The names follow SPEC §6.2, §7, and §8.1. They are not a stable signature. The first release aimed at this shape is v0.1 (M10), which waits on the write path, query, relaxation, and blobs. v1.0 is the format freeze (M15).

// Planned. Not exported by the persia crate.
let db = persia::Db::open("app.persia")?;
let products = db.create_collection(schema)?;
products.put(doc)?;
products.commit()?;

// A typo still returns hits. The response names the change (SPEC §7).
let results = products.search("runing")?;

Go and TypeScript will call that same Rust core in-process. See SDKs.

Format

The on-disk layout is a versioned format of this repository, specified in SPEC.md (draft v0.1). Anything written is little-endian and covered by a checksum. A layout change updates the SPEC, bumps a version or a feature flag, adds an ADR under docs/adr/, and adds a golden fixture. Segments are immutable once written.

unsafe is confined to modules an ADR names: the mmap reader (ADR-0010), mapped container reads (ADR-0017), and the OS calls std lacks (ADR-0021). Each unsafe block carries a // SAFETY: comment. Corrupt input is Err. The segment reader turns a bad segment into ReadError.

Term dictionaries are FSTs (fst pinned to 0.4.7, because the engine re-checks that parser). Column presence and postings deletions use Roaring bitmaps.

Architecture

Arrows point from a crate to the crates it is allowed to depend on (ALLOWED in xtask/src/check_deps.rs). The fuller map, including the write and query paths the SPEC describes, is docs/architecture.md.

flowchart TD
  cli["persia-cli"] --> persia["persia"]
  cli --> engine["persia-engine"]
  cli --> storage["persia-storage"]
  cli --> format["persia-format"]
  persia --> engine
  persia --> blob["persia-blob"]
  engine --> analysis["persia-analysis"]
  engine --> storage
  engine --> format
  blob --> storage
  blob --> format
  storage --> format

persia-server is drawn in docs/architecture.md above persia. It is an empty main today, so it stays out of the figure.

Status

MVP (M0–M15) is the v1.0 release. The live graph, the burn-up, and the ready-next list are PROGRESS.md. The checklist is ROADMAP.md. The same snapshot is on the roadmap page.

After v1.0

From the table under After v1.0 on main. None of these leaves are started (0 of 151).

v2.1, v2.2, and v2.3 are separate targets: UI components, AI search, and on-device storage. Geo stays on v3.0 with the enterprise format work. The ordering notes are in that ROADMAP section.

SDKs

Rust is the native API. The facade crate is persia. The libraries under it are what a Rust caller can use today, as in the quickstart.

Go and TypeScript embedded bindings are planned for v1.1 (M16). The design is ADR-0018 and docs/sdk/, and it is not implemented. One C ABI (persia-ffi) wraps persia. Go calls it through cgo (sdk/persia). TypeScript calls it through N-API (@persiadb/node) for Node.js, Bun, and Deno. Ranking, relaxation, and crash recovery stay in the Rust core.

Two other clients are a different product, also unstarted: network clients in Rust (persia-client) and Go (persia-go) speak gRPC to persia-server (SPEC §13, M14). A Python SDK is v1.2 (M21), after the embedded bindings.

Built with Claude Opus 5.5

This repository is built entirely with Claude Opus 5.5: the code, the tests, and the docs.

The engineering rules in CLAUDE.md bind those changes the same way they bind a human patch. SPEC.md is the contract. A byte string from disk, the network, or a user that fails a c