Skip to main content

SqliteRepository

Struct SqliteRepository 

Source
pub struct SqliteRepository { /* private fields */ }
Expand description

SQLite-backed repository for local storage

Implementations§

Source§

impl SqliteRepository

Source

pub fn inspect_pinned_file( &self, revision: &str, path: &str, max_bytes: u64, ) -> Result<FileInspection>

Verify one path under one pinned commit. Requires open_read_only so HEAD, commit metadata and every object belong to the same read snapshot. V1 header verification binds the root tree, not the unhashed change list or ancestor closure. File content is hashed as logical bytes, not codec bytes.

Source

pub fn inspect_pinned_file_into( &self, revision: &str, path: &str, max_bytes: u64, sink: &mut dyn Write, ) -> Result<FileInspection>

Self::inspect_pinned_file, streaming the decoded logical bytes into sink as they are hashed. The sink sees unverified bytes: a caller must discard them unless the returned status is verified (see oak file inspect --output, which stages into a temp file and publishes only after verification).

Source§

impl SqliteRepository

Source

pub fn inspect_refs(&self, max_branches: u64) -> Result<RefsInspection>

Read every local ref in one pinned snapshot. Requires open_read_only.

Source§

impl SqliteRepository

Source

pub fn inspect_pinned_tree( &self, revision: &str, limits: TreeInspectionLimits, ) -> Result<TreeInspection>

Verify and list one pinned commit’s whole tree within limits.

Source

pub fn visit_pinned_tree( &self, revision: &str, limits: TreeInspectionLimits, visitor: &mut dyn TreeFileSink, ) -> Result<TreeInspection>

Self::inspect_pinned_tree, streaming each file’s bytes through visitor (for materialization) while they are hashed. A begin or finish error aborts the walk and is returned.

Source§

impl SqliteRepository

Source

pub fn blob_descriptors( &self, hashes: &[&Hash], ) -> Result<Vec<Option<(u64, usize)>>>

(size, chunk reference count) of each stored blob, in order, without reading blob bytes; None for a blob not stored locally. One read transaction and two cached statements for the whole batch.

Source

pub fn open_read_only(db_path: &Path) -> Result<Self>

Inspect an existing repository in one SQLite read transaction. Does not create a database, migrate schema, chmod, or change journal mode. Normal SQLite locking remains enabled (WAL coordination sidecars may be used). Mutating Repository methods fail on this connection.

Source

pub fn open(db_path: &Path) -> Result<Self>

Open or create a SQLite repository at the given path

Source

pub fn open_relaxed(db_path: &Path) -> Result<Self>

Open or create a SQLite repository at the given path with foreign-key enforcement disabled.

Used by oak mount for its lazy blob cache: the mount stores a manifest whose entries reference blobs that haven’t been fetched yet. The default schema declares manifest_entries.blob_hash as a foreign key to blobs(hash); rusqlite enables enforcement by default, so inserts would fail. The mount cache is a private, per-mount store — relaxing FK enforcement is safe there because nothing else points at it.

Source

pub fn stored_blob_reader( &self, hash: &Hash, ) -> Result<Option<(u64, StoredBlobReader)>>

A sequential reader over a stored blob’s plaintext that never holds the whole blob: the stored row is read through SQLite incremental blob I/O on a private read-only connection (the repository’s own connection is not locked while the stream is open) and zstd rows are decoded as a stream. It reads committed state. Returns the blob’s declared size with the reader, or None when the blob has no content row. The caller verifies the bytes against the hash.

Source

pub fn database_path(&self) -> Result<PathBuf>

Source

pub fn store_change_capture( &self, capture_id: &str, change_set: &CanonicalChangeSetV1, owner: &str, name: &str, origin: Option<&str>, source_branch: &str, base_commit: Option<&Hash>, ) -> Result<()>

Atomically publish a complete canonical descriptor and one immutable local capture occurrence after rechecking the branch snapshot inside the write transaction. Identical portable changes share one descriptor; provenance rows are never replaced or deduplicated.

Source

pub fn get_change_capture( &self, capture_id: &str, ) -> Result<StoredChangeCapture>

Resolve one durable capture occurrence and rederive its complete canonical descriptor from the immutable base/result tree objects. Working-tree bytes are never rescanned and inherited blobs are not hydrated by this lookup.

Source

pub fn set_foreign_keys(&self, enabled: bool) -> Result<()>

The server’s PostgreSQL schema is more permissive than the client’s SQLite schema: parent_branch and parent_hash are unenforced on the server but FK-checked here. Bulk imports (e.g. oak clone) need to relax enforcement so that legitimate server data — branches whose parent has been deleted, or commits whose timestamp ordering doesn’t match topology — can be ingested. Always re-enable after the bulk load so subsequent normal operations stay validated.

Source

pub fn upsert_branch_metadata_at_generation( &self, branch: &Branch, observed_generation: i64, ) -> Result<bool>

Reconcile cached metadata with a remote row, retaining pending local descriptions.

store_branch is insert-only because local callers often create a placeholder branch row before later local edits. Remote refresh paths refresh lifecycle fields, but a locally edited description remains owned by the user until observed/published remotely with that exact value. Returns false when a newer local generation fenced out this response’s description. Lifecycle reconciliation still follows the caller policy.

Source

pub fn reconcile_pulled_branch_metadata( &self, branch: &Branch, observed_generation: i64, ) -> Result<bool>

Pull preserves existing local lifecycle decisions (e.g. an unsynced close) while refreshing descriptions that have no pending local edit. The parent branch is the exception: the server owns it (it restacks a branch when its parent lands), so a non-null remote parent always wins. Returns false if the response predates this branch’s local generation.

Source

pub fn description_generation(&self) -> Result<i64>

Capture before issuing a remote metadata request; never reconstruct this token from local state after the response arrives.

Source

pub fn branch_description_pending(&self, name: &str) -> Result<bool>

A description edited locally (or predating synchronization tracking) must not be replaced by a differing remote value.

Source

pub fn bulk_begin(&self) -> Result<()>

Begin a relaxed-durability transaction for a bulk ingest (clone / pull).

Lowers synchronous to NORMAL and opens a transaction, so the many per-object INSERTs that follow commit as a batch instead of fsync-ing once per statement. The default synchronous=FULL in WAL mode fsyncs on every auto-commit, and the clone ingest writes each chunk, blob, blob_chunks row, tree, and commit as its own statement — so that per-statement fsync dominates clone time on repos with many files. Subsequent store_* calls join this open transaction (SQLite leaves auto-commit mode while a manual BEGIN is active).

Pair with Self::bulk_flush (called periodically to bound WAL growth on a large import) and exactly one of Self::bulk_commit / Self::bulk_rollback. Single-writer only: the caller must not issue writes through another handle to the same database while the batch is open, or that write will silently join — and ride the fate of — this transaction.

Source

pub fn bulk_flush(&self) -> Result<()>

Commit the current bulk batch and immediately open the next, so a long import doesn’t accumulate its entire dataset in the WAL before a single final commit. Cheap under synchronous=NORMAL — no fsync until the next checkpoint.

Source

pub fn bulk_commit(&self) -> Result<()>

Commit the bulk transaction and restore full durability.

Source

pub fn bulk_rollback(&self)

Roll back an in-flight bulk transaction and restore full durability. Best-effort, for the error path so a failed import doesn’t leave a dangling transaction or a half-applied batch behind.

Source

pub fn write_txn_begin(&self) -> Result<()>

Begin a normal durable write transaction.

Unlike Self::bulk_begin, this deliberately leaves SQLite’s durability pragmas alone. Use it for small publication steps where the caller needs many repository setters to become observable as one unit.

Source

pub fn write_txn_commit(&self) -> Result<()>

Commit a transaction opened with Self::write_txn_begin.

Source

pub fn write_txn_rollback(&self)

Roll back a transaction opened with Self::write_txn_begin.

Source

pub fn delete_metadata(&self, key: MetadataKey) -> Result<()>

Remove a metadata row entirely (rather than storing an empty value).

Source

pub fn bulk_importer(&self, batch_size: usize) -> Result<BulkImporter>

Open a BulkImporter against the same database file.

The importer holds its own connection (so it can manage long-lived transactions independently of the regular repo’s mutex), batches writes across batch_size commits, and caches inserted-tree hashes in memory to skip per-subtree EXISTS lookups during deeply repetitive imports (e.g. oak clone <git-url> or oak init over an existing .git).

The caller must not concurrently issue writes via the underlying SqliteRepository until the importer is dropped or finished — SQLite only allows one writer at a time, and a clash will block.

Source

pub fn compact_storage(&self) -> Result<CompactStats>

One-shot storage compaction. Converts the database to the compact on-disk format and reclaims the freed space:

  1. Backfills trees.content for every legacy tree (one still stored as tree_entries rows), verifying each reconstructed tree re-hashes to its key before writing.
  2. Drops the now-unused tree_entries table (only if every tree has content, so the fallback path is never needed again).
  3. Re-compresses legacy raw blobs (codec = 0) that actually shrink.
  4. VACUUMs to shrink the file on disk.

Idempotent: a second run finds nothing to backfill/recompress and just VACUUMs. VACUUM needs transient free disk roughly equal to the final database size.

Source

pub fn replace_blob_chunks( &self, blob_hash: &Hash, chunks: &[ChunkInfo], ) -> Result<()>

Replace a blob’s chunk mapping wholesale. store_blob_chunks is INSERT OR IGNORE (append-only), which is right for ingest but can’t correct an existing mapping — needed when a blob arrives mis-chunked from a skewed server and the client re-chunks the repaired plaintext.

Source

pub fn delete_chunk(&self, hash: &Hash) -> Result<()>

Remove a cached chunk by content hash.

Lazy hydration uses this to discard a previously-persisted corrupt row before retrying the download. Blob-to-chunk mappings are intentionally left intact: migration 0009 made those references metadata hints, so a later hydration can still use them to fetch the missing bytes.

Trait Implementations§

Source§

impl Repository for SqliteRepository

Source§

fn store_manifest(&self, manifest: &Manifest) -> Result<()>

Write a manifest as a tree. The hash of manifest is already the tree root hash (computed by Manifest::new via build_tree), so this is just a tree-store of the corresponding nested structure.

Source§

fn get_manifest(&self, hash: &Hash) -> Result<Option<Manifest>>

Read a manifest by hash. Reads from the tree tables.

Source§

fn put_tree(&self, entries: Vec<ManifestEntry>) -> Result<Hash>

Optimized put_tree: builds the nested tree, then inserts all tree objects in a single transaction, skipping subtrees whose hash already exists. This is the key write-path optimization for tree storage.

Source§

fn store_blob(&self, blob: &Blob) -> Result<()>

Source§

fn put_blob_sources(&self, sources: Vec<BlobSource>) -> Result<Vec<Hash>>

Hash and store many blobs, returning each source’s canonical hash in input order. Each source’s read is invoked exactly once, possibly on a worker thread, to obtain the bytes to store. Semantically identical to a Repository::put_blob loop (which is the default impl), but it lets a backend overlap producing one blob’s content (e.g. reading a file) with hashing/encoding/storing another’s instead of forcing all-produce-then-all-hash barriers — which is what makes a snapshot of a few large files fast.
Source§

fn get_blob(&self, hash: &Hash) -> Result<Option<Blob>>

Source§

fn has_blob(&self, hash: &Hash) -> Result<bool>

Source§

fn has_blobs(&self, hashes: &[&Hash]) -> Result<Vec<bool>>

Repository::has_blob for many hashes, in order. Backends override it to answer a whole manifest’s presence check with one prepared statement instead of one round trip per entry.
Source§

fn get_blob_size(&self, hash: &Hash) -> Result<Option<u64>>

Source§

fn store_tree(&self, tree: &Tree) -> Result<()>

Source§

fn walk_tree(&self, root: &Hash) -> Result<Vec<ManifestEntry>>

Walk the tree rooted at root and return its flat entry list.
Source§

fn get_tree(&self, hash: &Hash) -> Result<Option<Tree>>

Source§

fn has_tree(&self, hash: &Hash) -> Result<bool>

Source§

fn close_branch( &self, name: &str, close_reason: Option<CloseReason>, ) -> Result<()>

Close a branch and optionally record an explicit close reason.
Source§

fn update_branch_close_reason( &self, name: &str, close_reason: CloseReason, ) -> Result<()>

Source§

fn store_branch(&self, branch: &Branch) -> Result<()>

Source§

fn get_branch(&self, name: &str) -> Result<Option<Branch>>

Source§

fn list_branches(&self) -> Result<Vec<Branch>>

Source§

fn list_branches_isolated( &self, ) -> Result<Vec<Result<Branch, UnreadableBranch>>>

Like Self::list_branches, but one stored row whose metadata cannot be decoded becomes an Err(UnreadableBranch) entry instead of failing the whole listing (fb-118). Batch assessment uses this so a single corrupt row cannot hide every other branch.
Source§

fn update_branch_status(&self, name: &str, status: BranchStatus) -> Result<()>

Source§

fn set_branch_parent(&self, name: &str, parent: Option<&str>) -> Result<()>

Re-parent an existing branch (restacking it). Unlike store_branch, which never touches an existing row, this overwrites parent_branch.
Source§

fn update_branch_description(&self, name: &str, description: &str) -> Result<()>

Source§

fn edit_branch_description(&self, name: &str, description: &str) -> Result<()>

Record user-authored text separately from server/import metadata updates.
Source§

fn description_publication_generation(&self) -> Result<Option<i64>>

Capture before reading description text for publication. Backends without local synchronization tracking return no token and do not acknowledge.
Source§

fn acknowledge_branch_description( &self, name: &str, description: Option<&str>, generation: Option<i64>, ) -> Result<()>

Acknowledge exact text and generation, without clearing a newer/ABA edit.
Source§

fn rename_branch(&self, old_name: &str, new_name: &str) -> Result<()>

Source§

fn delete_branch(&self, name: &str) -> Result<()>

Remove a branch row and its head pointer from local storage. Commits authored on the branch are untouched — commits.branch_name is a soft label. Deleting a branch that doesn’t exist is a no-op.
Source§

fn get_branch_head(&self, name: &str) -> Result<Option<Hash>>

Source§

fn set_branch_head(&self, name: &str, hash: &Hash) -> Result<()>

Source§

fn reconcile_remote_merge_branch_state( &self, closed_branch: &str, new_branch: &Branch, seed_head: &Hash, ) -> Result<()>

Atomically close a remotely-merged branch, create the fresh current branch, and point branch/HEAD metadata at seed_head. Read more
Source§

fn store_commit(&self, commit: &Commit) -> Result<()>

Source§

fn get_commit(&self, hash: &Hash) -> Result<Option<Commit>>

Source§

fn repair_commit_fields(&self, verified: &Commit) -> Result<bool>

Repair the commit row stored under verified.hash when its stored fields don’t reproduce that hash. store_commit keeps the first row it sees, so a row written with a placeholder author and the client’s clock (older oak merge binaries did this for the server’s squash commit) would otherwise never self-verify. Read more
Source§

fn has_commit(&self, hash: &Hash) -> Result<bool>

Source§

fn get_commits_for_branch(&self, branch_name: &str) -> Result<Vec<Commit>>

Source§

fn count_commits_for_branch(&self, branch_name: &str) -> Result<usize>

Number of commits authored directly on branch_name — rows whose branch_name column equals this branch. In Oak’s branch-per-session model a feature branch is seeded at its parent’s head with none of its own commits; each oak commit adds one, and a squash-merge moves you onto a fresh branch with zero again. So this count is exactly the branch’s local work not yet merged into its parent. Purely local — it never consults the server. Defaults to counting Repository::get_commits_for_branch; backends override it with a cheaper COUNT(*).
Source§

fn merge_child_exists(&self, branch_head: &Hash) -> Result<bool>

Fast negative check for “does any local commit claim this commit as its merge parent?” SQLite backs this with an index on commits.merge_parent_hash; the default implementation is only for backends without a native query path.
Source§

fn get_commits_since( &self, branch_name: &str, since: Option<&Hash>, ) -> Result<Vec<Commit>>

Source§

fn get_all_commits(&self) -> Result<Vec<Commit>>

Source§

fn get_metadata(&self, key: MetadataKey) -> Result<Option<String>>

Source§

fn set_metadata(&self, key: MetadataKey, value: &str) -> Result<()>

Source§

fn insert_metadata_if_absent( &self, key: MetadataKey, value: &str, ) -> Result<bool>

Write value only when key has no value yet; returns whether it was written. Backends that can should make this a single atomic statement so a concurrent writer’s value is never overwritten.
Source§

fn load_stat_cache(&self) -> Result<HashMap<String, StatCacheEntry>>

Load the entire stat cache as a path -> entry map.
Source§

fn update_stat_cache( &self, upserts: &[(String, StatCacheEntry)], removed: &[String], ) -> Result<()>

Apply a batch of stat-cache changes: upsert upserts (path + entry) and delete the paths in removed. Implementations should run this as one transaction. An empty batch must be a no-op so an unchanged oak status performs zero writes.
Source§

fn store_chunk(&self, hash: &Hash, content: &[u8]) -> Result<()>

Source§

fn get_chunk(&self, hash: &Hash) -> Result<Option<Vec<u8>>>

Source§

fn has_chunk(&self, hash: &Hash) -> Result<bool>

Source§

fn store_blob_chunks( &self, blob_hash: &Hash, chunks: &[ChunkInfo], ) -> Result<()>

Source§

fn get_blob_chunks(&self, blob_hash: &Hash) -> Result<Option<Vec<ChunkInfo>>>

Source§

fn put_commit_and_advance_refs( &self, branch_name: String, parent_hash: Option<Hash>, merge_parent_hash: Option<Hash>, entries: Vec<ManifestEntry>, author: String, message: Option<String>, timestamp: DateTime<Utc>, files: Vec<FileChange>, ) -> Result<Hash>

Build/store a manifest, create a commit for it, and advance the branch head plus legacy HEAD to that commit. Backends that can transactionally publish the whole transition should override this method.
Source§

fn put_tree_commit_and_advance_refs( &self, branch_name: String, parent_hash: Option<Hash>, merge_parent_hash: Option<Hash>, root: Hash, trees: &[Tree], author: String, message: Option<String>, timestamp: DateTime<Utc>, files: Vec<FileChange>, ) -> Result<Hash>

Self::put_commit_and_advance_refs for a snapshot that already exists as trees — a tree-level merge’s result — so the whole tree is never rebuilt from a flat entry list. root is the commit’s root tree; trees are the ones not stored yet (every other tree under root must already be). Backends that can publish the whole transition in one transaction should override this method.
Source§

fn hash_blob_content(&self, content: &[u8]) -> Hash

The hash this backend would assign content via Self::put_blob, computed without storing anything. Read-only paths (oak status, restore previews) compare working files against manifest entries with this; BLAKE3 by default, the git blob OID on the git backend.
Source§

fn resolve_path_in_tree( &self, root: &Hash, path: &str, ) -> Result<Option<TreeEntry>>

Resolve a /-separated path to a TreeEntry within the tree at root.
Source§

fn subtree_at_path(&self, root: &Hash, path: &str) -> Result<Option<Hash>>

Return the hash of the subtree at path (must be a directory). An empty path returns Some(root).
Source§

fn put_blob(&self, content: Vec<u8>) -> Result<Hash>

Hash and store a blob’s content. Returns the backend’s canonical hash.
Source§

fn put_manifest(&self, entries: Vec<ManifestEntry>) -> Result<Hash>

Build and store a manifest from the given entries. Returns the backend’s canonical hash for the manifest (a tree OID on the git backend).
Source§

fn put_commit( &self, branch_name: String, parent_hash: Option<Hash>, merge_parent_hash: Option<Hash>, manifest_hash: Hash, author: String, message: Option<String>, _timestamp: DateTime<Utc>, files: Vec<FileChange>, ) -> Result<Hash>

Build and store a commit. Returns the backend’s canonical commit hash. Read more
Source§

fn get_head(&self) -> Result<Option<Hash>>

Source§

fn set_head(&self, hash: &Hash) -> Result<()>

Source§

fn get_remote_url(&self) -> Result<Option<String>>

Source§

fn get_current_branch_name(&self) -> Result<Option<String>>

Source§

fn set_current_branch(&self, name: &str) -> Result<()>

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.