Struct Database 

pub struct Database<S: Store = FileStore> { /* private fields */ }

Opened ModelVault database: generic over a Store (FileStore on disk, VecStore in memory).

Implementations

impl<S: Store> Database<S>

pub fn register_model<T: DbModel>( &mut self, ) -> Result<(CollectionId, SchemaVersion), DbError>

Register the collection schema defined by T (schema version 1).

pub fn register_collection( &mut self, name: &str, fields: Vec<FieldDef>, primary_field: &str, ) -> Result<(CollectionId, SchemaVersion), DbError>

Create a new collection at schema version 1.

primary_field must name a single-segment (top-level) field present in fields. Appends a catalog segment and updates the in-memory catalog.

pub fn register_collection_with_indexes( &mut self, name: &str, fields: Vec<FieldDef>, indexes: Vec<IndexDef>, primary_field: &str, ) -> Result<(CollectionId, SchemaVersion), DbError>

pub fn register_schema_version( &mut self, id: CollectionId, fields: Vec<FieldDef>, ) -> Result<SchemaVersion, DbError>

Bump the schema version for id to current + 1 with a new field set.

The primary-key field must remain present as a top-level field (see catalog rules).

pub fn register_schema_version_with_indexes( &mut self, id: CollectionId, fields: Vec<FieldDef>, indexes: Vec<IndexDef>, ) -> Result<SchemaVersion, DbError>

pub fn plan_schema_version_with_indexes( &self, id: CollectionId, fields: Vec<FieldDef>, indexes: Vec<IndexDef>, ) -> Result<MigrationPlan, DbError>

Plan a schema version bump and return the required migration steps, if any.

pub fn backfill_top_level_field_with_value( &mut self, collection_id: CollectionId, field: &str, value: RowValue, ) -> Result<(), DbError>

Backfill a missing top-level field with a fixed value for all rows in a collection.

This helper is intentionally simple so it can be bound to other languages.

pub fn backfill_field_at_path_with_value( &mut self, collection_id: CollectionId, path: &FieldPath, value: RowValue, ) -> Result<(), DbError>

Backfill a missing field (any segment path) with a fixed value for all rows.

pub fn rebuild_indexes_for_collection( &mut self, collection_id: CollectionId, ) -> Result<(), DbError>

Rebuild index entries for all rows in collection_id using the current schema’s index defs.

pub fn register_schema_version_with_indexes_force( &mut self, id: CollectionId, fields: Vec<FieldDef>, indexes: Vec<IndexDef>, ) -> Result<SchemaVersion, DbError>

Force-register a new schema version, bypassing compatibility checks.

This is an escape hatch for advanced workflows where the caller performs an out-of-band data rewrite (or accepts inconsistent index/query behavior until a rebuild).

impl<S: Store> Database<S>

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

Write a durable checkpoint segment and publish it via the superblock.

The checkpoint stores the logical state (catalog + latest rows + index state) so open can avoid scanning/replaying the full log. Works with any Store (file-backed FileStore or VecStore snapshots).

impl Database<FileStore>

pub fn compact_to(&self, dest_path: impl AsRef<Path>) -> Result<(), DbError>

Rewrite the database into a compacted single-file image at dest_path.

The destination file is truncated/overwritten if it exists.

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

pub fn export_snapshot_to_path( &mut self, dest_path: impl AsRef<Path>, ) -> Result<(), DbError>

Create a consistent backup copy of this on-disk database.

This writes a checkpoint (for fast reopen and a stable state marker) and then copies the underlying file bytes to dest_path.

pub fn restore_snapshot_to_path( snapshot_path: impl AsRef<Path>, dest_path: impl AsRef<Path>, ) -> Result<(), DbError>

Restore a snapshot file into dest_path by atomically replacing the destination.

This is a file operation helper intended for operational tooling.

impl<S: Store> Database<S>

pub fn path(&self) -> &Path

Path passed to Database::open, or ":memory:" for crate::storage::VecStore.

pub fn recovery_info(&self) -> &OpenRecoveryInfo

Recovery metadata from the most recent open (truncation, etc.).

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

Rebuild secondary indexes from latest rows and compare to replayed index state.

pub fn catalog(&self) -> &Catalog

Read-only view of the schema catalog built from Schema segments.

On same-process attached read-only handles, prefer Self::collection_names and Self::collection_id_named for live metadata; this borrows the open-time snapshot.

pub fn snapshot_catalog(&self) -> Catalog

Clone of the live schema catalog (always current on attached read-only handles).

pub fn collection_names(&self) -> Vec<String>

All registered collection names in lexicographic order.

pub fn index_state(&self) -> &IndexState

Read-only access to the in-memory secondary index state (rebuilt from Index segments).

On same-process attached read-only handles this returns the index state captured at open; use Self::snapshot_index_state for a live clone after writer updates.

pub fn snapshot_index_state(&self) -> IndexState

Clone of the live secondary index state (always current on attached read-only handles).

pub fn query( &self, q: &Query, ) -> Result<Vec<BTreeMap<String, RowValue>>, DbError>

Execute a query against the current in-memory snapshot of the database.

pub fn explain_query(&self, q: &Query) -> Result<String, DbError>

Return a human-readable explanation of the chosen plan for q.

pub fn query_iter(&self, q: &Query) -> Result<QueryRowIter<'_>, DbError>

Lazy iterator over query rows (same semantics as Self::query).

See crate::query::QueryRowIter — this is the v0.7 pull-based execution boundary, not a full operator graph.

pub fn collection<'a, T: DbModel>( &'a self, ) -> Result<Collection<'a, S, T>, DbError>

Typed handle over a registered collection; T may be a subset model.

pub fn collection_id_named(&self, name: &str) -> Result<CollectionId, DbError>

Look up CollectionId by collection name (leading/trailing whitespace trimmed).

Returns SchemaError::UnknownCollectionName when the name is not registered.

pub fn get( &self, collection_id: CollectionId, pk: &ScalarValue, ) -> Result<Option<BTreeMap<String, RowValue>>, DbError>

Return the latest stored row for pk, or None if no insert has been replayed for that key.

pk must match the declared primary field’s crate::schema::Type.

impl<S: Store> Database<S>

pub fn transaction<R>( &mut self, f: impl FnOnce(&mut Self) -> Result<R, DbError>, ) -> Result<R, DbError>

Run f inside a multi-write transaction: durable segments are written on success.

On error, staged work is discarded and nothing new is appended to the log.

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

Start a transaction (for bindings that cannot use the closure API). Pairs with Self::commit_transaction or Self::rollback_transaction.

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

Commit the active transaction started with Self::begin_transaction.

pub fn rollback_transaction(&mut self)

Discard the active transaction without writing to the log.

pub fn insert( &mut self, collection_id: CollectionId, row: BTreeMap<String, RowValue>, ) -> Result<(), DbError>

Insert or replace the row for collection_id identified by its primary-key field.

row maps top-level field names to RowValue. The primary key field must be present. Only single-segment field paths are supported in 0.6.x.

pub fn delete( &mut self, collection_id: CollectionId, pk: &ScalarValue, ) -> Result<(), DbError>

Delete the row for collection_id identified by its primary key.

impl Database<FileStore>

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

Open an existing file or create a new database at path.

Creates parent directories as needed via the OS; the file is opened read/write.

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

Open an existing file read-only (does not create it).

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

Open with recovery and other options (see crate::config::OpenOptions).

impl Database<VecStore>

pub fn open_in_memory() -> Result<Self, DbError>

New empty in-memory database (same on-disk layout as a new file image in a VecStore).

pub fn open_in_memory_with_options(opts: OpenOptions) -> Result<Self, DbError>

In-memory open with crate::config::OpenOptions.

pub fn from_snapshot_bytes(bytes: Vec<u8>) -> Result<Self, DbError>

Deserialize a full database image from bytes (e.g. from into_snapshot_bytes).

pub fn into_snapshot_bytes(self) -> Vec<u8>

Consume self and return the owned byte buffer backing the store.

pub fn snapshot_bytes(&self) -> Vec<u8>

Clone of the full serialized database image (alias of the buffer returned by into_snapshot_bytes).

pub fn export_snapshot_to_path( &self, dest_path: impl AsRef<Path>, ) -> Result<(), DbError>

Write the full in-memory database image to dest_path.

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

Open an in-memory database from a snapshot file.