Struct Db 

pub struct Db { /* private fields */ }

Open OXGDB database handle.

Performance

Moving a handle is O(1): it moves the current Arc<Snapshot> and the open delta-log handle.

Implementations

impl Db

pub fn create(path: impl AsRef<Path>) -> Result<Self, DbError>

Creates a new empty OXGDB database at path.

The create order is base-0 then empty delta-0.log then the writer lock file then the superblock (written LAST as the create-complete marker), so a half-created store is detected on open rather than silently opened empty.

Errors

Returns DbError::AlreadyExists when a store already exists, or DbError::Io/DbError::InvalidStore when creation fails.

Performance

This function is O(empty base bytes).

pub fn open(path: impl AsRef<Path>) -> Result<Self, DbError>

Opens an existing OXGDB database, recovering the live frontier from the valid prefix of the delta-log replayed over the base named by the superblock.

Errors

Returns DbError when the store is missing, malformed, or the log is corrupt beyond a torn tail.

Performance

This function is O(base bytes + log bytes).

pub const fn live_generation(&self) -> CheckpointGeneration

Returns the live base generation named by the superblock (the count of folds this store has undergone; gen-0 is the freshly created store).

Performance

This method is O(1).

pub const fn checkpoint_policy(&self) -> CheckpointPolicy

Returns the configured auto-checkpoint policy.

Performance

This method is O(1).

pub const fn set_checkpoint_policy(&mut self, policy: CheckpointPolicy)

Sets the auto-checkpoint policy consulted after each dirty commit.

Performance

This method is O(1).

pub fn validate(&self) -> Result<(), DbError>

Validates the current handle by re-reading the superblock and verifying the live base’s content CRC.

Errors

Returns DbError when the superblock or base fails validation.

Performance

This method is O(base bytes).

pub fn validate_path(path: impl AsRef<Path>) -> Result<(), DbError>

Validates an OXGDB database at path.

Errors

Returns DbError when the store fails to open and recover.

Performance

This function is O(base bytes + log bytes).

pub fn compact(&mut self) -> Result<(), DbError>

Folds the current base+overlay into a new base generation, rotating the delta-log and republishing the superblock (a manual checkpoint).

This is the checkpoint primitive, exposed here so the existing compact API keeps its “rewrite the store compactly” contract. Auto-triggering is configured separately via Db::set_checkpoint_policy.

Errors

Returns DbError when encoding, writing, or publishing the new generation fails.

Performance

This method is O(visible state bytes).

pub fn stats(&self) -> Stats

Returns operational status for this handle, including the live generation count and the on-disk base/delta-log sizes the auto-checkpoint policy weighs.

Performance

This method is O(visible state) for the merged counts plus two stat syscalls for the file sizes.

pub fn catalog_summary(&self) -> CatalogSummary

Returns a catalog-size summary.

Performance

This method is O(catalog entry count).

pub fn reader(&self) -> Reader

Starts a read transaction pinned to the current visible snapshot.

Performance

This method is O(1): the reader clones the current Arc<Snapshot> and observes a fixed state even across later commits and checkpoints.

pub fn read<R>( &self, f: impl FnOnce(&Reader) -> Result<R, DbError>, ) -> Result<R, DbError>

Runs f against a read transaction pinned to the current snapshot. The primary read entry point.

Errors

Propagates whatever error f returns.

Performance

Entering is O(1) (an Arc clone); the total cost is f’s cost.

pub fn write<R>( &mut self, f: impl FnOnce(&mut Writer<'_>) -> Result<R, DbError>, ) -> Result<(R, CommitOutcome), DbError>

Runs f against the single write transaction, committing on Ok and rolling back on Err — control flow IS the commit protocol. Returns f’s value with the CommitOutcome (whether a durable frame landed). The primary write entry point.

Errors

Returns DbError::WriterLockHeld when another writer holds the lock, f’s error (after rolling back the staged delta), or a commit error.

Performance

Begin is O(1); commit is O(change). A triggered auto-fold adds O(visible bytes).

pub fn bind(&self, schema: &Schema) -> Result<Bound, DbError>

Resolves an already-applied Schema against the live catalog WITHOUT writing, returning the Bound handle bag (for a store already bootstrapped with this schema).

Errors

Returns DbError::UnknownName when a declared item is absent.

Performance

This method is O(declared items × log catalog).

pub fn prepare(&self, query: &str) -> Result<PreparedQuery, DbError>

Prepares a query against the current catalog.

Errors

Returns DbError when parsing or semantic analysis fails.

Performance

This method is O(query length + catalog lookup cost).