Struct Database 

pub struct Database { /* 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 Database

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 Database::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 checkpoint(&mut self) -> Result<(), DbError>

Folds the current base+overlay into base-{g+1}, creates an empty delta-{g+1}.log, republishes the superblock naming g+1 (the linearization point), then unlinks the old base and log.

The order is crash-safe: the new base is fully durable BEFORE the superblock names it (so a crash before the superblock leaves the OLD superblock authoritative and the orphan new base is ignored), and the old base/log are unlinked only AFTER the superblock names the new generation (so a crash before the unlink leaves the NEW superblock authoritative and the orphan old files are ignored). The [crate::wire::SuperblockRecord] rename is the single linearization point.

Errors

Returns DbError when encoding, writing, or publishing fails.

Performance

This method is O(visible state bytes).

pub fn status(&self) -> DatabaseStatus

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 begin_read(&self) -> ReadTransaction

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 begin_write(&mut self) -> Result<WriteTransaction<'_>, DbError>

Starts the single writer transaction, acquiring the cross-process writer lock for the transaction’s lifetime.

Errors

Returns DbError::WriterLockHeld when another writer holds the lock or DbError::TransactionIdOverflow when writer ids are exhausted.

Performance

This method is O(1): the writer layers a fresh empty write overlay over the current snapshot.

pub fn prepare( &self, language: QueryLanguage, 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).