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 open_with_credentials( root: impl AsRef<Path>, username: &str, password: &str, ) -> Result<Self>

Open an existing plaintext database that has require_auth = true, verifying the supplied credentials up front and caching the resolved [Principal] on the returned handle. Every subsequent operation will be checked against that principal.

Returns MongrelError::AuthNotRequired if the database does not have require_auth enabled — callers must pick the matching constructor for the database’s mode. Returns MongrelError::InvalidCredentials on a bad username/password.

See docs/15-credential-enforcement.md.

pub fn open_with_credentials_and_options( root: impl AsRef<Path>, username: &str, password: &str, options: OpenOptions, ) -> Result<Self>

Open with credentials and a configurable cross-process lock timeout. Mirrors open_with_options for the credentialed path.

pub fn open_with_options( root: impl AsRef<Path>, options: OpenOptions, ) -> Result<Self>

Open an existing database with non-default OpenOptions.

Use this when you need cross-process lock retries (lock_timeout_ms) rather than the fail-fast default. The other open constructors keep their previous defaults; use their *_with_options variants when they need the same timeout behavior.

pub fn create_with_credentials( root: impl AsRef<Path>, admin_username: &str, admin_password: &str, ) -> Result<Self>

Create a fresh plaintext database with require_auth = true and a single admin user. The returned handle is already authenticated as that admin — every subsequent operation is checked against the admin principal (which bypasses all permission checks via is_admin).

This is the bootstrap path: there is no window where the database requires auth but has no users.

See docs/15-credential-enforcement.md.

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 materialized_view(&self, name: &str) -> Option<MaterializedViewEntry>

pub fn materialized_views(&self) -> Vec<MaterializedViewEntry>

pub fn security_catalog(&self) -> SecurityCatalog

pub fn security_active_for(&self, table: &str) -> bool

pub fn set_security_catalog(&self, security: SecurityCatalog) -> Result<()>

Persist a complete validated RLS/masking catalog through the WAL.

pub fn set_security_catalog_as( &self, security: SecurityCatalog, principal: Option<&Principal>, ) -> Result<()>

Persist security policy changes on behalf of an explicit request principal.

pub fn require_for( &self, principal: Option<&Principal>, permission: &Permission, ) -> Result<()>

pub fn principal_snapshot(&self) -> Option<Principal>

pub fn require_columns_for( &self, table: &str, operation: ColumnOperation, column_ids: &[u16], principal: Option<&Principal>, ) -> Result<()>

pub fn select_column_ids_for( &self, table: &str, principal: Option<&Principal>, ) -> Result<Vec<u16>>

pub fn secure_rows_for( &self, table: &str, rows: Vec<Row>, principal: Option<&Principal>, ) -> Result<Vec<Row>>

pub fn rows_for( &self, table: &str, principal: Option<&Principal>, ) -> Result<Vec<Row>>

Read visible rows with column authorization, RLS, and masks applied.

pub fn count_for( &self, table: &str, principal: Option<&Principal>, ) -> Result<u64>

Count rows visible to a principal without bypassing RLS.

pub fn put_for( &self, table: &str, cells: Vec<(u16, Value)>, principal: Option<&Principal>, ) -> Result<RowId>

Authorize and write one native-API row for an explicit principal.

pub fn check_row_policy_for( &self, table: &str, command: PolicyCommand, row: &Row, check_new: bool, principal: Option<&Principal>, ) -> Result<()>

pub fn set_materialized_view( &self, definition: MaterializedViewEntry, ) -> Result<()>

Durably create or replace a materialized-view definition after its physical table has been populated.

pub fn root(&self) -> &Path

The filesystem root this database was opened/created at.

pub fn is_read_only_replica(&self) -> bool

pub fn set_replication_wal_retention_segments(&self, segments: usize)

pub fn replication_snapshot(&self) -> Result<ReplicationSnapshot>

Capture a consistent bootstrap image. DDL, transaction spill/publish, direct table commits, compaction, and WAL append are quiesced while the file image is read. WAL records newer than manifests remain sufficient for recovery, so no flush or compaction is required.

pub fn hot_backup(&self, destination: impl AsRef<Path>) -> Result<BackupReport>

Create an online, directly-openable backup at destination.

The short boundary phase quiesces commits/DDL, syncs the WAL, copies mutable metadata, and pins the exact immutable runs named by the copied manifests. Writers resume while those runs stream into a sibling staging directory. A checksummed backup manifest is written last, then the stage is atomically renamed into place.

pub fn replication_batch_since( &self, since_epoch: u64, ) -> Result<ReplicationBatch>

Return complete committed transactions after since_epoch. A gap or a transaction backed by a spilled run requires a fresh bootstrap image.

pub fn append_replication_batch(&self, records: &[Record]) -> Result<u64>

Durably append a leader batch to a follower’s local WAL. The caller must drop and reopen this handle to run ordinary WAL recovery before it advances _meta/repl_epoch.

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 require_auth_enabled(&self) -> bool

Returns true if this database’s catalog has require_auth = true. When true, every operation consults the cached [Principal] via require.

pub fn principal(&self) -> Option<Principal>

A snapshot of the cached principal for this handle, if any. None for databases opened without credentials (the default). Returns a clone because the principal lives behind an RwLock.

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

Re-resolve the cached principal from the on-disk catalog. Long-lived handles (e.g. a daemon) call this after a REVOKE or role change — possibly made by a different handle to the same database — to pick up the new effective permissions without re-verifying the password.

This reloads the catalog from disk first, so changes committed by other handles (or other processes) are visible. The username is taken from the existing cached principal; if the user has since been dropped, returns MongrelError::InvalidCredentials.

No-op (returns Ok(())) on a credentialless database, or on a credentialed database whose cached principal is None.

pub fn enable_auth( &self, admin_username: &str, admin_password: &str, ) -> Result<()>

Convert a credentialless database to a credentialed one: create the first admin user, set require_auth = true, and cache the admin principal on this handle so subsequent operations on the same handle continue to work. After this call, the database can only be reopened via open_with_credentials / open_encrypted_with_credentials.

Refuses if the database already has require_auth = true. This is the conversion path for existing databases; for fresh databases, create_with_credentials sets everything up atomically.

See docs/15-credential-enforcement.md.

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

Disable require_auth on this database, reverting it to credentialless mode. This is the recovery path — it requires the handle to already be open (and therefore already authenticated if require_auth was on).

After this call, the database can be reopened with plain open / open_encrypted without credentials. All existing users and roles are preserved in the catalog (so require_auth can be re-enabled without recreating them), but they are no longer consulted for enforcement.

For true offline recovery (when credentials are lost and no authenticated handle is available), the caller opens the database directly via the catalog file (filesystem access required) and calls this method — see the CLI’s auth disable-offline command.

See docs/15-credential-enforcement.md §4.7.

pub fn require(&self, perm: &Permission) -> Result<()>

Enforcement check: if the catalog has require_auth = true, verify that the cached principal satisfies perm. Called by every enforcement point (DDL, admin, maintenance, and — in Phase 2 — Table/Transaction/MongrelSession operations).

On a credentialless database this is a no-op (Ok(())).

pub fn require_table(&self, table: &str, perm: RequiredPermission) -> Result<()>

Convenience: enforce a table-level permission (Select/Insert/ Update/Delete) by table name. Used by the Transaction layer and other callers that know the operation kind + table name but don’t want to construct the full Permission enum value themselves.

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 ephemeral SQL NOTIFY messages. Durable row changes use Self::change_events_since, with Self::subscribe_change_commits as a low-latency wake-up.

pub fn subscribe_change_commits(&self) -> Receiver<()>

pub fn change_events_since( &self, last_event_id: Option<&str>, ) -> Result<CdcBatch>

Reconstruct committed row changes from the retained shared WAL. Event ids are stable <commit_epoch>:<operation_index> pairs. A caller that resumes before the oldest retained commit receives gap = true and must rebootstrap instead of silently skipping changes.

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 call_procedure_as( &self, name: &str, args: HashMap<String, Value>, principal: Option<&Principal>, ) -> Result<ProcedureCallResult>

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

Begin a new transaction reading at the current visible epoch.

pub fn begin_as(&self, principal: Option<Principal>) -> Transaction<'_>

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 begin_with_external_trigger_bridge_as<'a>( &'a self, bridge: &'a dyn ExternalTriggerBridge, principal: Option<Principal>, ) -> Transaction<'a>

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 transaction_with_external_trigger_bridge_as<'a, T>( &'a self, bridge: &'a dyn ExternalTriggerBridge, principal: Option<Principal>, f: impl FnOnce(&mut Transaction<'_>) -> Result<T>, ) -> Result<T>

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 set_history_retention_epochs(&self, epochs: u64) -> Result<()>

Configure a rolling history window measured in prior commit epochs. The first enable starts at the current epoch because earlier versions may already have been compacted. Increasing the window likewise cannot recreate history that fell outside the previous guarantee.

pub fn history_retention_epochs(&self) -> u64

pub fn earliest_retained_epoch(&self) -> Epoch

pub fn snapshot_at_owned( &self, epoch: Epoch, ) -> Result<(Snapshot, OwnedSnapshotGuard)>

Pin a guaranteed historical epoch for the lifetime of the returned guard. Rejects future epochs and epochs outside the configured window.

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 unless TTL has expired rows to reclaim. 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 has_ttl_tables(&self) -> bool

Whether any mounted table has wall-clock TTL retention. SQL sessions use this to avoid epoch-keyed result caches that can outlive a cutoff.

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 set_table_ttl( &self, table_name: &str, column_name: &str, duration_nanos: u64, ) -> Result<TtlPolicy>

Set a timestamp-column TTL policy and WAL-log it for crash recovery and replication. Duration is in nanoseconds.

pub fn clear_table_ttl(&self, table_name: &str) -> Result<()>

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 checkpoint(&self) -> Result<()>

Produce a deterministic-stable byte image of the database directory.

After checkpoint():

• All pending writes are flushed to sorted runs (no memtable data).
• Each table is compacted to a single sorted run (no run fragmentation).
• All non-active WAL segments are deleted (data is durable in runs).
• The active WAL segment is rotated to a fresh empty segment.
• Dropped-table directories are removed.
• All manifests + catalog are persisted.

The resulting directory is byte-stable: git add captures a snapshot that git checkout restores deterministically. No stale WAL tail bytes, no unbounded segment growth, no mutable-run spill files.

This is the engine primitive behind mongreldb snapshot <dir> (CLI). It does NOT clear the exclusive lock — the caller still owns the database handle.

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.

impl Database

pub fn create_pitr_archive( &self, destination: impl AsRef<Path>, ) -> Result<PitrArchiveReport>

Initialize a PITR archive with a consistent online base backup.

pub fn archive_pitr( &self, archive: impl AsRef<Path>, ) -> Result<PitrArchiveReport>

Append all complete commits since the archive watermark. Spilled-run commits are converted to ordinary logical Put records while their run payload remains available. A retention gap fails closed.

Trait Implementations

impl Debug for Database

Manual Debug for Database — surfaces the diagnostics-relevant fields (root, epoch, table count, encryption/auth state) without requiring every internal type (Table, GroupCommit, broadcast sender, etc.) to impl Debug. The raw field types carry locks, trait objects, and channels that have no useful Debug output, so a hand-written impl is clearer than peppering #[allow(dead_code)] skip attributes across two dozen fields.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.