Struct Database 

pub struct Database { /* private fields */ }

A kit database handle.

Wraps a MongrelDB core database and a kit schema, providing table metadata and transaction creation.

Implementations

impl Database

pub fn open(path: &Path) -> Result<Self>

Open an existing kit database.

pub fn open_encrypted(path: &Path, passphrase: &str) -> Result<Self>

Open an existing page-encrypted kit database with its passphrase.

pub fn create_encrypted( path: &Path, schema: KitSchema, passphrase: &str, ) -> Result<Self>

Create a fresh page-encrypted kit database (AES-256-GCM; the passphrase derives the key hierarchy). Columns flagged encrypted / encrypted_indexable are encrypted at rest.

pub fn create(path: &Path, schema: KitSchema) -> Result<Self>

Create a fresh kit database with the given schema.

pub fn open_with_credentials( path: &Path, username: &str, password: &str, ) -> Result<Self>

Open an existing kit database that has require_auth = true, verifying credentials up front. Every subsequent operation is checked against the authenticated principal’s permissions.

Returns an error if the database does not have require_auth enabled (use open for credentialless databases) or if the credentials are invalid.

See docs/15-credential-enforcement.md.

pub fn create_with_credentials( path: &Path, schema: KitSchema, admin_username: &str, admin_password: &str, ) -> Result<Self>

Create a fresh kit database with require_auth = true, a single admin user, and the given schema. The returned handle is already authenticated as the admin.

See docs/15-credential-enforcement.md.

pub fn open_encrypted_with_credentials( path: &Path, passphrase: &str, username: &str, password: &str, ) -> Result<Self>

Open an existing page-encrypted kit database that has require_auth = true, combining the encryption passphrase with credential verification.

pub fn create_encrypted_with_credentials( path: &Path, schema: KitSchema, passphrase: &str, admin_username: &str, admin_password: &str, ) -> Result<Self>

Create a fresh page-encrypted kit database with require_auth = true and a single admin user. Composes encryption-at-rest with credential enforcement.

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

Convert a credentialless kit database to a credentialed one in place. Creates the first admin user, sets require_auth = true, and caches the admin principal on this handle.

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

Disable require_auth, reverting to credentialless mode. The recovery path — requires an open (already-authenticated) handle. Users and roles are preserved but no longer enforced.

pub fn require_auth_enabled(&self) -> bool

Returns true if this database has require_auth = true.

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

Re-resolve the cached principal from the on-disk catalog, picking up role/permission changes made by other handles. No-op on credentialless databases.

pub fn register_default( &mut self, name: impl Into<String>, provider: impl Fn() -> Value + Send + Sync + 'static, )

Register a named default provider used by DefaultKind::CustomName columns. Returns the database for chaining.

pub fn raw(&self) -> &CoreDatabase

The raw, unguarded MongrelDB core database. This is the Rust analogue of the TypeScript kit’s nativeDb escape hatch: writes made directly against it bypass all kit constraints.

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

Application table names, excluding the reserved __kit_* tables.

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

pub fn replace_procedure(&self, spec: &ProcedureSpec) -> Result<StoredProcedure>

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

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

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

pub fn replace_trigger(&self, spec: &TriggerSpec) -> Result<StoredTrigger>

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

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

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

pub fn allocate_sequence(&self, name: &str, count: i64) -> Result<i64>

Allocate count values from the named sequence, returning the first allocated value. A fresh sequence starts at 1 (SQL AUTO_INCREMENT semantics). The allocation runs in its own committed transaction and retries on write-write conflicts.

pub fn transaction<T, F>(&self, max_retries: usize, f: F) -> Result<T>

where F: FnMut(&mut Transaction<'_>) -> Result<T>,

Run f inside a kit transaction, committing on success and retrying on retryable write-write conflicts up to max_retries times.

pub fn table(&self, name: &str) -> Option<&KitTable>

Look up a table definition by name.

pub fn schema(&self) -> &KitSchema

Return the currently loaded schema.

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

Begin a new kit transaction.

pub fn set_schema(&mut self, schema: KitSchema)

Replace the in-memory schema, usually after a migration.

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

Verify that the sidecar schema file and all reserved __kit_* tables are present.

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

Reclaim orphaned runs and stale WAL/shadow files; returns the count removed. Safe to run on a live database.

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

Verify run footer checksums; returns any integrity issues as JSON objects (table_id, table_name, severity, description). Empty ⇒ healthy.

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

Drop corrupt runs; returns the ids of the runs that were dropped.

pub fn snapshot_epoch(&self) -> u64

The current visible commit epoch — a monotonically increasing version stamp. A committed write bumps it; a snapshot at this epoch sees all currently-committed data.

pub fn export_tsv(&self, table: &str) -> Result<String>

Export every visible row of table as a TSV document (header row of column names, tab-separated cells, NULL = empty field). See crate::tsv for the escaping rules.

pub fn import_tsv(&self, table: &str, text: &str) -> Result<usize>

Import a TSV document into table (one committed transaction). Each row passes through defaults, validation, and constraint checks like a normal insert. Returns the number of rows inserted.

pub fn explain(&self, table: &str, predicate: &Expr) -> Result<ExplainPlan>

Describe how predicate would be executed against table: which native index conditions push down, whether the push-down is exact (no residual re-filtering), and whether any index acceleration applies at all. A pure diagnostic — it plans but does not run the query.

pub fn rows_at_epoch(&self, table: &str, epoch: u64) -> Result<Vec<Row>>

Read every row of table visible at commit epoch — a point-in-time (MVCC time-travel) read. epoch must not exceed the current snapshot epoch. Rows reclaimed by GC/compaction for retired snapshots may no longer be reconstructable; this reads whatever the engine still retains at that epoch.

pub fn approx_aggregate( &self, table: &str, column: Option<&str>, agg: ApproxAggKind, z: f64, ) -> Result<Option<ApproxAggregate>>

Estimate an aggregate over table from the engine’s reservoir sample, returning a point estimate and a z-score confidence interval (e.g. z = 1.96 for ~95%). column is required for Sum/Avg and ignored for Count. Returns None when the reservoir is empty (no sampled rows yet). Fast and O(sample) — trades exactness for speed on large tables.

pub fn scan_batched<F>( &self, table: &str, batch_size: usize, f: F, ) -> Result<()>

where F: FnMut(&[Map<String, Value>]) -> Result<()>,

Stream table in row batches without materializing the whole table at once. f receives successive chunks of at most batch_size value-maps, all from one snapshot. Backed by the engine’s native scan cursor when the table has a sorted run; for an overlay-only table (no run yet) it falls back to a single in-memory pass, still chunked to batch_size.

pub fn set_similarity( &self, table: &str, column: &str, query: &[String], k: usize, ) -> Result<Vec<SimilarRow>>

Rank rows of table by Jaccard set-similarity between query and the string set stored (as a JSON array) in column, returning the top k with similarity > 0, highest first — the dedup/join primitive.

When column has a MinHash index, candidate rows come from the engine’s LSH index (sub-linear) and are then re-verified with exact Jaccard, so the top-k is exact for the recalled candidates (LSH recall is high but < 100%). Without an index it is an exact linear scan.

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

Flush every table’s in-memory writes to durable sorted runs. Besides durability, this empties the memtable, which is what enables the engine’s incremental-aggregate fast path (see Self::incremental_aggregate).

pub fn incremental_aggregate( &self, table: &str, column: Option<&str>, agg: IncrementalAggKind, filter: Option<&Expr>, ) -> Result<IncrementalAggregate>

Maintain and read an aggregate over table that updates by merging only newly-committed rows instead of rescanning. column is required for Sum/Min/Max/Avg and ignored for Count. An optional filter restricts the aggregate; it must translate exactly to index conditions (no residual), otherwise this errors — an inexact filter would silently aggregate the wrong rows.

The engine keeps a per-(table, column, agg, filter) cached state and, on a warm cache with an advanced epoch and no deletes/pending writes, folds in just the delta. The returned value is always exact; the incremental flag reports whether the fast path was taken.

pub fn applied_migrations(&self) -> Result<Vec<Migration>>

Return the migrations already recorded in __kit_schema_migrations.

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

Best-effort flush-on-close (§4.4): force-flush pending writes on every table to .sr sorted runs so WAL segments stay bounded across repeated short-lived process invocations (e.g. the CLI). Call as the last action before exit. The daemon does not need this (auto-compactor handles it).

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

Compact all tables: merge sorted runs into one clean run each so query latency stays flat. Returns (compacted, skipped). Safe to run at any time — honors snapshot retention. The daemon’s background auto-compactor already does this periodically; this is for manual/cron use.

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

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

pub fn rename_table(&mut self, from: &str, to: &str) -> Result<()>

Rename a live table. Fails if from does not exist or to is already in use; a no-op when from == to. Names beginning with __kit_ are reserved for internal tables and rejected here (parity with the TypeScript kit).

Updates both the engine table and the kit schema catalog (in memory and persisted to kit_schema.json), so subsequent table_names(), table(name), and transactional reads by the new name all work. Foreign keys in other tables that reference from are retargeted to to.

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

Rebuild statistics/metadata for every table’s indexes (the engine’s ANALYZE equivalent: ensure_indexes_complete on each table). Safe to run at any time; useful after bulk loads so the query planner and learned indexes have fresh data.

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

Reclaim space across all tables: compacts every table’s sorted runs, then runs gc. Returns the count of reclaimed orphaned runs/files. Equivalent to the engine’s VACUUM. Safe to run at any time.

pub fn create_view(&self, spec: &ViewSpec) -> Result<()>

Create a SQL view (CREATE VIEW <name> AS <select>). The engine overwrites any existing view with the same name, so this also serves as replace. The view lives in the kit’s long-lived SQL session — it is not persisted to the catalog, so reopening the database loses it (re-apply a CreateView migration to restore).

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

Drop a SQL view by name (idempotent — DROP VIEW IF EXISTS).

pub fn reserve_auto_inc(&self, table: &str) -> Result<Option<i64>>

Reserve (without inserting) the next engine-native AUTO_INCREMENT value for table, advancing the per-table counter. Returns None when the table has no auto-increment column. This is the escape hatch for callers that stage a row with an explicit id inside a transaction; the reservation becomes durable when a row carrying the id commits, and an unused reservation just leaves a gap. Parity with the TypeScript kit’s reserveAutoIncSync.

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

Create a catalog 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.

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

Grant or revoke admin privileges on a user.

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

List all usernames.

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

Create a role.

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

Drop a role.

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

List all role names.

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 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, rows are written as a uniform-epoch pending run instead of streamed Put records.

pub fn set_recursive_triggers(&self, enabled: bool)

Enable or disable recursive trigger execution (database-wide).

pub fn trigger_config(&self) -> TriggerConfig

Read the current trigger execution policy.

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

Set the trigger execution policy. max_depth must be > 0.

pub fn set_table_compaction_zstd_level( &self, table: &str, level: i32, ) -> Result<()>

Set a table’s compaction zstd level (-1 = default, 0 = none, 1..22).

pub fn set_table_result_cache_max_bytes( &self, table: &str, max_bytes: u64, ) -> Result<()>

Set a table’s result-cache max bytes.

pub fn set_table_mutable_run_spill_bytes( &self, table: &str, bytes: u64, ) -> Result<()>

Set a table’s mutable-run spill threshold (bytes).

pub fn set_table_sync_byte_threshold( &self, table: &str, threshold: u64, ) -> Result<()>

Set a table’s WAL sync byte threshold (bytes between group-syncs).

pub fn set_table_index_build_policy( &self, table: &str, policy: IndexBuildPolicy, ) -> Result<()>

Set a table’s index build policy (Deferred for fast ingest, Eager for fast first query).

pub fn table_page_cache_stats(&self, table: &str) -> Result<CacheStats>

Page-cache statistics for a table.

pub fn table_run_count(&self, table: &str) -> Result<usize>

Number of sorted runs a table currently has (compaction target: 1).

pub fn table_memtable_len(&self, table: &str) -> Result<usize>

Memtable length (uncommitted staged rows) for a table.

pub fn table_mutable_run_len(&self, table: &str) -> Result<usize>

Mutable-run length for a table.

pub fn table_page_cache_len(&self, table: &str) -> Result<usize>

Page-cache entry count for a table.

pub fn table_decoded_cache_len(&self, table: &str) -> Result<usize>

Decoded-page-cache entry count for a table.

pub fn sql(&self, statement: &str) -> Result<Vec<RecordBatch>>

Run a SQL statement through the embedded MongrelSession (DataFusion frontend) and return the result as Arrow [RecordBatch]es. This is the Rust analogue of the TypeScript kit’s db.sql(sql) (which returns Arrow IPC bytes) and the NAPI Database.sql.

Read statements return their rows; DDL/DML (e.g. CREATE VIEW, ANALYZE, VACUUM, CREATE VIRTUAL TABLE) return an empty vec. Writes made directly through SQL bypass Kit-level constraints (defaults, enums, min/max, length, regex, triggers) — use the transactional Transaction API for constrained writes. The engine’s own declarative constraints (unique, FK, check) still apply.

The session is held for the database’s lifetime, so session-scoped objects (views, prepared statements, the result cache) persist across calls — mirroring a long-lived database connection. After a migration that creates/drops tables, call Database::refresh_sql_session so the session sees the new table set.

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

(Re)build the cached SQL session so it sees the current table set. The engine’s MongrelSession snapshots the table list at construction; this rebuilds it after a migration creates or drops tables. Views and other session-scoped state are reset.

pub fn sql_arrow(&self, statement: &str) -> Result<Vec<u8>>

Like Database::sql, but returns the result serialized as Arrow IPC file bytes — the same wire format the NAPI addon and the daemon emit. Decode with pyarrow.ipc.open_file, the JS apache-arrow tableFromIPC, or crate::arrow_util::read_arrow_ipc. Empty for DDL/DML.

pub fn sql_rows(&self, statement: &str) -> Result<Vec<Map<String, Value>>>

Like Database::sql, but materializes the result rows into JSON-style maps (column name → value) for callers that don’t want to take a direct Arrow dependency. Empty for DDL/DML.