pub struct Db { /* private fields */ }Expand description
Open OXGDB database handle.
§Performance
Moving a handle is O(1): it moves the current Arc<Snapshot> and the open
delta-log handle.
Implementations§
Source§impl Db
impl Db
Sourcepub const fn checkpoint_policy(&self) -> CheckpointPolicy
pub const fn checkpoint_policy(&self) -> CheckpointPolicy
Sourcepub const fn set_checkpoint_policy(&mut self, policy: CheckpointPolicy)
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).
Sourcepub fn validate(&self) -> Result<(), DbError>
pub fn validate(&self) -> Result<(), DbError>
Validates the current handle with the strongest offline check:
re-reads the superblock, verifies the live base’s container integrity
in full (oxgraph_snapshot::Snapshot::open_checked for the table
checksum, then oxgraph_snapshot::Snapshot::verify_all over EVERY
section — a mismatch names the failing section kind), and finally
attaches the base to run the structural bind checks (format version,
property sort order, posting bounds).
§Errors
Returns DbError when the superblock or base fails validation; a
checksum failure names the failing section.
§Performance
This method is O(base bytes): one verify_all sweep plus one
verify-at-bind attach (two checksum passes over the base).
Sourcepub fn compact(&mut self) -> Result<(), DbError>
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).
Source§impl Db
impl Db
Sourcepub fn create(path: impl AsRef<Path>) -> Result<Self, DbError>
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::Storage(crate::error::StorageError::AlreadyExists)] when a store already
exists, or [DbError::Io]/[DbError::InvalidStore] when creation fails.
§Performance
This function is O(empty base bytes).
Sourcepub fn open(path: impl AsRef<Path>) -> Result<Self, DbError>
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). Base integrity is fused
into the bind pass: the container’s table checksum is verified once,
then each bound section’s payload CRC-32C is verified as the section is
borrowed — there is no separate whole-base CRC scan.
Source§impl Db
impl Db
Sourcepub const fn live_generation(&self) -> CheckpointGeneration
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).
Sourcepub fn stats(&self) -> Stats
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.
Sourcepub fn catalog_summary(&self) -> CatalogSummary
pub fn catalog_summary(&self) -> CatalogSummary
Sourcepub fn reader(&self) -> Reader
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.
Sourcepub fn pin(&self) -> ReadPin
pub fn pin(&self) -> ReadPin
Returns the pin identifying the current visible snapshot — the commit
sequence and checkpoint generation a Self::reader started now would
observe — without starting a read transaction.
§Performance
This method is O(1): it copies the current snapshot’s identity fields.
Sourcepub fn write<R>(
&mut self,
f: impl FnOnce(&mut Writer<'_>) -> Result<R, DbError>,
) -> Result<(R, CommitOutcome), DbError>
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::Txn(crate::error::TxnError::WriterLockHeld)] when another writer holds
the lock, f’s error (after rolling back the staged delta), or a commit error.
§Performance
Begin is O(parent change) — the writer seeds by cloning the parent
overlay’s delta map structure (label sets, text values, per-subject
property delta maps, and index postings are Arc-shared, so each of
the N committed-but-unfolded entries costs O(1); folded away by a
checkpoint). Commit is O(change). A triggered auto-fold adds
O(visible bytes).