Struct Database 

pub struct Database { /* private fields */ }

A multi-table database: one catalog, one epoch clock, shared caches, a shared WAL, and a live map of name → Arc<Table>.

Implementations

impl Database

pub fn create(root: impl AsRef<Path>) -> Result<Self>

Create a fresh plaintext database at root.

pub fn open(root: impl AsRef<Path>) -> Result<Self>

Open an existing plaintext database.

pub fn visible_epoch(&self) -> Epoch

The current reader-visible epoch.

pub fn catalog_snapshot(&self) -> Catalog

Clone the in-memory catalog (for diagnostics / tests).

pub fn root(&self) -> &Path

The filesystem root this database was opened/created at.

pub fn table_id(&self, name: &str) -> Result<u64>

Resolve a table name → id (live tables only). pub(crate) so the transaction layer can stage by name.

pub fn procedures(&self) -> Vec<StoredProcedure>

pub fn procedure(&self, name: &str) -> Option<StoredProcedure>

pub fn create_procedure( &self, procedure: StoredProcedure, ) -> Result<StoredProcedure>

pub fn create_or_replace_procedure( &self, procedure: StoredProcedure, ) -> Result<StoredProcedure>

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

pub fn users(&self) -> Vec<UserEntry>

List all catalog users (password hashes included — callers should not serialize them externally).

pub fn roles(&self) -> Vec<RoleEntry>

List all catalog roles.

pub fn create_user(&self, username: &str, password: &str) -> Result<UserEntry>

Create a new user with an Argon2id-hashed password.

pub fn drop_user(&self, username: &str) -> Result<()>

Drop a user by username.

pub fn alter_user_password( &self, username: &str, new_password: &str, ) -> Result<()>

Change a user’s password.

pub fn verify_user( &self, username: &str, password: &str, ) -> Result<Option<UserEntry>>

Verify credentials. Returns Some(entry) on success, None on mismatch, Err on engine error.

pub fn set_user_admin(&self, username: &str, is_admin: bool) -> Result<()>

Grant admin privileges to a user (bypasses all permission checks).

pub fn create_role(&self, name: &str) -> Result<RoleEntry>

Create a new role.

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

Drop a role by name.

pub fn grant_role(&self, username: &str, role_name: &str) -> Result<()>

Grant a role to a user.

pub fn revoke_role(&self, username: &str, role_name: &str) -> Result<()>

Revoke a role from a user.

pub fn grant_permission( &self, role_name: &str, permission: Permission, ) -> Result<()>

Grant a permission to a role.

pub fn revoke_permission( &self, role_name: &str, permission: Permission, ) -> Result<()>

Revoke a permission from a role.

pub fn resolve_principal(&self, username: &str) -> Option<Principal>

Resolve a user into a crate::auth::Principal by collecting all permissions from their roles. Returns None if the user doesn’t exist.

pub fn check_permission(&self, username: &str, permission: &Permission) -> bool

Check whether a user has a specific permission (via their roles).

pub fn triggers(&self) -> Vec<StoredTrigger>

pub fn trigger(&self, name: &str) -> Option<StoredTrigger>

pub fn create_trigger(&self, trigger: StoredTrigger) -> Result<StoredTrigger>

pub fn create_or_replace_trigger( &self, trigger: StoredTrigger, ) -> Result<StoredTrigger>

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

pub fn external_tables(&self) -> Vec<ExternalTableEntry>

pub fn external_table(&self, name: &str) -> Option<ExternalTableEntry>

pub fn create_external_table( &self, entry: ExternalTableEntry, ) -> Result<ExternalTableEntry>

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

pub fn commit_external_table_state( &self, name: &str, state: &[u8], ) -> Result<Epoch>

pub fn trigger_config(&self) -> TriggerConfig

pub fn set_trigger_config(&self, config: TriggerConfig) -> Result<()>

pub fn set_recursive_triggers(&self, recursive: bool)

pub fn subscribe_changes(&self) -> Receiver<ChangeEvent>

Subscribe to change-data-capture events. Returns a receiver that yields ChangeEvents for every committed Put/Delete/NOTIFY.

pub fn notify(&self, channel: &str, message: Option<String>)

Publish a notification message on a named channel. Reaches all active subscribers (daemon /events, application listeners).

pub fn call_procedure( &self, name: &str, args: HashMap<String, Value>, ) -> Result<ProcedureCallResult>

pub fn begin(&self) -> Transaction<'_>

Begin a new transaction reading at the current visible epoch.

pub fn begin_with_isolation(&self, level: IsolationLevel) -> Transaction<'_>

Begin a transaction with a specific isolation level.

pub fn begin_with_external_trigger_bridge<'a>( &'a self, bridge: &'a dyn ExternalTriggerBridge, ) -> Transaction<'a>

Begin a transaction whose trigger programs may route external-table DML through an application/query-layer module bridge.

pub fn transaction<T>( &self, f: impl FnOnce(&mut Transaction<'_>) -> Result<T>, ) -> Result<T>

Run f in a transaction; commit on Ok, rollback on Err.

pub fn transaction_with_external_trigger_bridge<'a, T>( &'a self, bridge: &'a dyn ExternalTriggerBridge, f: impl FnOnce(&mut Transaction<'_>) -> Result<T>, ) -> Result<T>

Run f in a transaction with an external-trigger bridge; commit on Ok, rollback on Err.

pub fn snapshot(&self) -> (Snapshot, SnapshotGuard<'_>)

Register a read snapshot at the current visible epoch and return it with a guard that retains it for GC until dropped.

pub fn snapshot_owned(&self) -> (Snapshot, OwnedSnapshotGuard)

Owned (clonable-handle) variant of Self::snapshot for cross-thread retention.

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

Names of all live tables.

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

Best-effort flush-on-close (§4.4): force-flush every mounted table that has pending writes to a .sr sorted run, so WAL segments can be reaped on the next open. Call this as the last action before a short-lived process (CLI, one-shot script) exits. The daemon does not need this — its background auto-compactor handles run management.

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

Compact every mounted table: merge all sorted runs into one clean run so query cost stays flat (single-run fast path) instead of growing with run count. Tables with < 2 runs are skipped (no-op). Each table is locked individually for its own compaction; snapshot retention is honored by Table::compact. Returns (tables_compacted, tables_skipped).

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

Compact a single table by name. Returns Ok(true) if it was compacted, Ok(false) if skipped (< 2 runs).

pub fn table(&self, name: &str) -> Result<TableHandle>

Look up a live table by name.

pub fn create_table(&self, name: &str, schema: Schema) -> Result<u64>

Create a new table. The DDL is first logged to the shared WAL (Op::Ddl(CreateTable) + TxnCommit) and group-synced so it is durable BEFORE the in-memory catalog and table map are mutated; the catalog checkpoint is rewritten afterwards (spec §15, review fix #16). A reopen that sees a stale catalog still recovers the table by replaying the Ddl.

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

Logically drop a table, logging the DDL through the shared WAL first.

pub fn rename_table(&self, name: &str, new_name: &str) -> Result<()>

Rename a live table. name must exist and new_name must not collide with any live table; both checks run under ddl_lock so they are atomic with the rename and with concurrent create_table existence checks (no TOCTOU window). A no-op rename (name == new_name) succeeds without side-effects. The rename is logged to the shared WAL as DdlOp::RenameTable and recovered on reopen; the table_id, schema, and on-disk layout are unchanged (the table is keyed by table_id, so the in-memory object does not move — only the catalog name changes).

pub fn alter_column( &self, table_name: &str, column_name: &str, change: AlterColumn, ) -> Result<ColumnDef>

pub fn gc(&self) -> Result<usize>

Retention-gated garbage collection (spec §6.4, §7.4, §16). Deletes:

• Dropped-table subdirs whose at_epoch < min_active_snapshot.
• Stale _txn/ dirs (aborted/crashed large-txn pending runs).

Returns the number of items reclaimed.

pub fn set_spill_threshold(&self, bytes: u64)

Set the per-table spill threshold (bytes). When a transaction’s staged bytes for a single table exceed this, the rows are written as a uniform-epoch pending run instead of streamed Put records (spec §8.5).

pub fn check(&self) -> Vec<CheckIssue>

Verify multi-table integrity (spec §16). For every live table this: authenticates the manifest; opens each RunRef’s file through RunReader, which verifies the run footer checksum and — for encrypted DBs — the keyed run-metadata MAC; checks each run’s physical row count against its RunRef; flags RunRefs whose file is missing (dangling) and .sr files on disk that no RunRef references (orphan); and verifies flushed_epoch <= current_epoch. Returns the list of issues found (empty = healthy). Orphans are warning-severity; all other findings are error-severity (so Self::doctor quarantines them).

Cost: O(total run bytes) — the footer checksum is verified over each run’s full body, so this is an integrity tool, not a hot path.

pub fn doctor(&self) -> Result<Vec<u64>>

Quarantine unreadable tables (spec §16). Moves corrupt table dirs to _quarantine/<table_id>/, marks them dropped in the catalog, and unmounts them from the live table map so the DB still opens.