pub struct Db { /* private fields */ }Expand description
An embedded, in-memory database with Git semantics.
Db is a handle: cloning it is cheap and every clone refers to the same
database. It is Send + Sync, and readers never block writers.
use memfork_core::{Db, MergePolicy, Value};
let db = Db::new();
db.put("main", "plan:1", Value::new("draft"))?;
// Fork before a risky step; the parent cannot see the attempt.
db.fork("main", "try")?;
db.put("try", "plan:1", Value::new("rewritten"))?;
assert_eq!(db.get("main", "plan:1")?.map(|e| e.value.clone()), Some("draft".into()));
// It worked: fold it back in.
db.merge("try", "main", MergePolicy::Fail)?;
assert_eq!(db.get("main", "plan:1")?.map(|e| e.value.clone()), Some("rewritten".into()));Implementations§
Source§impl Db
impl Db
Sourcepub fn with_default_branch(name: &str) -> Result<Self>
pub fn with_default_branch(name: &str) -> Result<Self>
Create a database whose default branch has a name other than main.
Sourcepub fn default_branch(&self) -> &str
pub fn default_branch(&self) -> &str
The name of the branch that cannot be discarded.
Sourcepub fn set_journal(&self, journal: Option<Arc<dyn Journal>>)
pub fn set_journal(&self, journal: Option<Arc<dyn Journal>>)
Record every change to a journal before it becomes visible.
The engine does no I/O of its own: the journal decides where the bytes go and how durable they are. Attached after recovery rather than at construction, because replay must not re-record what it is replaying.
A library caller gets no journal unless they ask. The memfork binary
attaches one by default, because an agent’s memory that forgets
everything on restart is not what anyone means by memory.
Sourcepub fn is_journalled(&self) -> bool
pub fn is_journalled(&self) -> bool
Whether changes are being recorded.
Sourcepub fn set_eviction(&self, config: Option<EvictionConfig>)
pub fn set_eviction(&self, config: Option<EvictionConfig>)
Set a memory budget, or remove one.
With no budget nothing is ever evicted and reads record nothing, so they stay lock-free. Setting one turns on the reading history that scoring needs, which costs a brief per-branch lock per read.
Sourcepub fn eviction(&self) -> Option<EvictionConfig>
pub fn eviction(&self) -> Option<EvictionConfig>
The memory budget, if one is set.
Sourcepub fn on_evict(&self, hook: Option<OnEvict>)
pub fn on_evict(&self, hook: Option<OnEvict>)
Be told about entries before they are evicted, so they can be kept somewhere else.
Sourcepub fn enforce_budget(&self, branch: &str) -> Result<Option<CommitId>>
pub fn enforce_budget(&self, branch: &str) -> Result<Option<CommitId>>
Evict from a branch until it is under budget, as its own commit.
Called after a commit lands. Does nothing without a budget, and nothing when the branch is already under it, so the common path costs one lock-free read of the configuration.
Sourcepub fn embedding_dim(&self) -> Option<usize>
pub fn embedding_dim(&self) -> Option<usize>
The embedding dimension this database is pinned to, if any entry has carried an embedding yet (DESIGN §4.1).
Sourcepub fn has_branch(&self, branch: &str) -> bool
pub fn has_branch(&self, branch: &str) -> bool
Whether a branch exists.
Sourcepub fn branches(&self) -> Vec<BranchInfo>
pub fn branches(&self) -> Vec<BranchInfo>
Every branch, in ascending name order.
Sourcepub fn read(&self, branch: &str) -> Result<ReadView>
pub fn read(&self, branch: &str) -> Result<ReadView>
A consistent view of a branch as it is right now (DESIGN §4.3).
Sourcepub fn at(&self, branch: &str, seq: u64) -> Result<ReadView>
pub fn at(&self, branch: &str, seq: u64) -> Result<ReadView>
A view of a branch as it was after commit number seq (DESIGN §4.2).
Sequence numbers are monotonic along a branch’s first-parent chain, so
seq names exactly one commit: 0 is the empty genesis state and
head.seq is the present.
Sourcepub fn get(&self, branch: &str, key: &str) -> Result<Option<Arc<Entry>>>
pub fn get(&self, branch: &str, key: &str) -> Result<Option<Arc<Entry>>>
Read one key from a branch head.
Sourcepub fn list(
&self,
branch: &str,
prefix: &str,
limit: Option<usize>,
) -> Result<Vec<(String, Arc<Entry>)>>
pub fn list( &self, branch: &str, prefix: &str, limit: Option<usize>, ) -> Result<Vec<(String, Arc<Entry>)>>
List the keys of a branch that start with prefix, in ascending order.
Sourcepub fn search(
&self,
branch: &str,
query: &[f32],
k: usize,
prefix: Option<&str>,
) -> Result<Vec<SearchHit>>
pub fn search( &self, branch: &str, query: &[f32], k: usize, prefix: Option<&str>, ) -> Result<Vec<SearchHit>>
Exact brute-force cosine similarity search (DESIGN §4.2).
Sourcepub fn log(&self, branch: &str, limit: Option<usize>) -> Result<Vec<LogEntry>>
pub fn log(&self, branch: &str, limit: Option<usize>) -> Result<Vec<LogEntry>>
The first-parent history of a branch, newest first.
Sourcepub fn resolve(&self, reference: &str) -> Result<Arc<Commit>>
pub fn resolve(&self, reference: &str) -> Result<Arc<Commit>>
Resolve a branch name or a full hex commit id to a commit.
Sourcepub fn diff(&self, a: &str, b: &str) -> Result<Vec<Change>>
pub fn diff(&self, a: &str, b: &str) -> Result<Vec<Change>>
Key-level differences between two branches or commits, sorted by key.
Sourcepub fn begin(&self, branch: &str) -> Result<Txn>
pub fn begin(&self, branch: &str) -> Result<Txn>
Open a transaction on a branch (DESIGN §4.2).
The transaction records the branch head it was based on. Dropping it without committing is a rollback that leaves no trace.
Sourcepub fn put(&self, branch: &str, key: &str, value: Value) -> Result<CommitId>
pub fn put(&self, branch: &str, key: &str, value: Value) -> Result<CommitId>
Write one key as a single-operation transaction.
Sourcepub fn delete(&self, branch: &str, key: &str) -> Result<CommitId>
pub fn delete(&self, branch: &str, key: &str) -> Result<CommitId>
Remove one key as a single-operation transaction.
Sourcepub fn apply_record(&self, record: &Record) -> Result<()>
pub fn apply_record(&self, record: &Record) -> Result<()>
Rebuild state from journal records, in the order they were written.
Commit ids are recomputed, never read from the record, so a replay that produces the original ids is evidence the engine is deterministic rather than evidence that bytes were copied faithfully.
Sourcepub fn fork(&self, from: &str, new_branch: &str) -> Result<CommitId>
pub fn fork(&self, from: &str, new_branch: &str) -> Result<CommitId>
Point a new branch at another branch’s head (DESIGN §4.2).
Constant time and constant space whatever the database holds: the new branch is one pointer into the same immutable commit, and the two branches go on sharing every node until one of them is written to.
Sourcepub fn fork_at(
&self,
from: &str,
seq: u64,
new_branch: &str,
) -> Result<CommitId>
pub fn fork_at( &self, from: &str, seq: u64, new_branch: &str, ) -> Result<CommitId>
Point a new branch at a past commit of another branch (DESIGN §4.2).
Sourcepub fn branch_from_commit(
&self,
new_branch: &str,
at: CommitId,
) -> Result<CommitId>
pub fn branch_from_commit( &self, new_branch: &str, at: CommitId, ) -> Result<CommitId>
Point a new branch at an arbitrary commit.
Sourcepub fn discard(&self, branch: &str) -> Result<()>
pub fn discard(&self, branch: &str) -> Result<()>
Delete a branch and free every commit only it could reach (DESIGN §4.2).
The default branch cannot be discarded. Any ReadView already handed
out stays valid: it holds its commit alive by reference count.
Sourcepub fn discarded(&self) -> Vec<Discarded>
pub fn discarded(&self) -> Vec<Discarded>
The most recently discarded branches, oldest first, at most
DISCARDS_REMEMBERED of them.
Sourcepub fn all_commits(&self) -> Vec<Arc<Commit>>
pub fn all_commits(&self) -> Vec<Arc<Commit>>
Every commit the graph holds, in id order: what a history view draws.
Sourcepub fn commit_count(&self) -> usize
pub fn commit_count(&self) -> usize
How many commits the graph currently holds. Tests use this to show that a rolled-back transaction and a discarded branch leave nothing behind.
Source§impl Db
impl Db
Sourcepub fn merge(
&self,
source: &str,
target: &str,
policy: MergePolicy,
) -> Result<MergeOutcome>
pub fn merge( &self, source: &str, target: &str, policy: MergePolicy, ) -> Result<MergeOutcome>
Merge source into target against their common ancestor (DESIGN §4.2).
A key is in conflict only when both sides changed it to different
content. Under MergePolicy::Fail a conflict returns
Error::MergeConflict with every conflicting key and changes
nothing at all.