Crate obj 

obj — embedded document database (public crate).

This crate is the user-facing surface of the obj storage engine. It wraps the obj-core building blocks (pager, WAL, B+tree, codec, catalog, transaction layer) into the typed Db / Collection<T> API described in design.md.

Quick start

use obj::{Db, Document};
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize)]
struct Order { customer_id: u64, total_cents: u64 }

impl Document for Order {
    const COLLECTION: &'static str = "orders";
    const VERSION: u32 = 1;
}

fn run() -> obj::Result<()> {
    let db = Db::open("app.obj")?;
    let id = db.insert(Order { customer_id: 1, total_cents: 100 })?;
    let back: Option<Order> = db.get(id)?;
    assert!(back.is_some());
    Ok(())
}

unsafe policy

This crate is #![forbid(unsafe_code)]. All unsafe lives in obj-core::platform.

Structs

Collection

Typed handle to a collection.

CollectionStat

Per-collection summary inside DbStat.

Config

Db open-time configuration. Construct via Config::default and modify with the builder methods.

Db

The embedded document database.

DbStat

One-shot snapshot of a database’s header + catalog summary.

DumpIter

Streaming iterator returned by Db::dump_raw.

DumpRecord

One raw record yielded by DumpIter.

EnumVariantSchema

One variant of a DynamicSchema::Enum description.

Id

Per-collection document identifier.

IndexSpec

A runtime index declaration.

IntegrityReport

Structured result of an integrity check.

IterAll

Streaming iterator returned by Db::iter_all.

Query

The M8 query builder.

ReadTxn

Public read transaction. Acquired by crate::Db::read_transaction.

WriteTxn

Public write transaction.

Enums

DynamicSchema

Describes the byte-stream shape of a postcard-encoded payload at one version. See module docs for the variant ↔ wire-format mapping.

Error

The pager-level error type.

IndexKind

What kind of secondary index a given IndexSpec declares.

IntegrityFailure

Categorical reasons an integrity walk records a failure. Every variant carries the locus of the problem (page id, collection, index name, document id) so an operator can root-cause without re-running the check.

LockKind

Lock category for Error::Busy. Three variants because the three categories of contention produce different operator guidance: a contended cross-process WRITER_LOCK means another process is writing; a contended WriterInProcess means another thread of the same process is writing; a contended reader lock is unusual (31 slots, shared) and indicates either a saturated 31+-process workload or a stale lock left by a frozen process.

SyncMode

Durability mode for FileHandle::sync_data.

Constants

MAX_DISTINCT_IDS

Per-call cap on the bounded HashSet<Id> used by Collection::count_distinct_ids_in_range to count unique document Ids under an Each index. Power-of-ten Rule 3: the distinct set is allocation-bounded; exceeding the cap surfaces obj_core::Error::DistinctCountExceeded rather than chewing arbitrary memory. The user can narrow the range via .index_range(...) to fit inside the budget.

MAX_SORT_BUFFER

Default cap on the in-memory sort buffer. The query layer reads at most this many surviving documents into RAM before sorting; a scan that produces more candidates surfaces Error::SortBufferExceeded. M8 #66.

Traits

Document

The trait every user document type implements.

Schema

A type whose postcard wire shape is describable by a DynamicSchema.

Type Aliases

Result

Crate-local Result alias. Use this in new code unless an explicit std::result::Result is required for trait-impl reasons.

Derive Macros

Document

#[derive(obj::Document)] proc-macro re-export.