Struct DatabaseHandle 

pub struct DatabaseHandle { /* private fields */ }

A lightweight caller-specific handle onto one shared [DatabaseCore] (spec §10.1, S1A-001).

Obtained from crate::manager::DatabaseManager::open_shared. Cloning or dropping a handle has no storage side effects; storage closes when the last core reference drops or Self::shutdown runs.

Implementations

impl DatabaseHandle

pub fn identity(&self) -> &HandleIdentity

The identity bound to this handle.

pub fn access(&self) -> HandleAccess

The access restriction bound to this handle.

pub fn shares_core_with(&self, other: &Self) -> bool

Whether two handles reference the exact same process-local core.

pub fn lifecycle_state(&self) -> LifecycleState

The current lifecycle state of the shared core (S1A-004).

pub fn operation_guard(&self) -> Result<OperationGuard>

Admit one operation against the shared core (S1A-004). The RAII guard releases the operation slot on drop; new operations are rejected once the core leaves LifecycleState::Open.

pub fn query( &self, table: &str, query: &Query, projection: Option<&[u16]>, ) -> Result<Vec<Row>>

Execute an authorized native query with live roles, RLS, masks, and column grants.

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

Count rows visible to this handle after live authorization and RLS.

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

Return all rows visible to this handle after RLS and masks.

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

Create a table through this handle’s live principal.

pub fn put(&self, table: &str, cells: Vec<(u16, Value)>) -> Result<Option<i64>>

Atomically insert one row through this handle’s live principal.

pub fn put_batch( &self, table: &str, rows: Vec<Vec<(u16, Value)>>, ) -> Result<Vec<Option<i64>>>

Atomically insert many rows through this handle’s live principal (P1.4).

pub fn update( &self, table: &str, row_id: RowId, cells: Vec<(u16, Value)>, ) -> Result<OwnedRow>

Atomically update one row through this handle’s live principal (P1.4).

pub fn session(&self) -> Result<AuthorizedMongrelSession<'_>>

Open an authorized session bound to this handle’s principal (P1.4-T1).

Full SQL MongrelSession lives in the query crate (avoids core→query dependency). This session is the authorized CRUD/transaction wrapper without raw core escape.

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

Begin an authorized multi-statement transaction (P1.4-T2).

Writes through the returned AuthorizedTransaction re-check the handle’s read-only restriction. Commit/rollback are explicit.

pub fn delete(&self, table: &str, row_id: RowId) -> Result<()>

Atomically delete one row through this handle’s live principal.

pub fn create_index(&self, table: &str, definition: IndexDef) -> Result<u64>

Create a secondary index through this handle’s live principal (P1.4-T3).

Requires DDL permission (and fails on a read-only handle). Uses the same product path as SQL CREATE INDEX (Database::create_index).

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

Drop a secondary index by name through this handle’s live principal (P1.4-T3).

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

Create a stored procedure through this handle’s live principal (P1.4-X6).

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

Drop a stored procedure by name (P1.4-X6).

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

Call a stored procedure through this handle’s live principal (P1.4-X6).

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

Create a trigger through this handle’s live principal (P1.4-X6).

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

Drop a trigger by name (P1.4-X6).

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

Historical rows visible to this principal at snapshot (P1.4-X7).

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

Create a catalog user. Admin only.

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

Drop a catalog user. Admin only.

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

Create a role. Admin only.

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

Grant a role to a catalog user. Admin only.

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

Revoke a role from a catalog user. Admin only.

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

Grant one permission to a role. Admin only.

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

Revoke one permission from a role. Admin only.

pub fn register_service_principal( &self, token_id: impl Into<String>, principal_id: [u8; 16], permissions: Vec<Permission>, raw_secret: &str, expires_unix: u64, ) -> Result<ServicePrincipalDefinition>

Register an authenticated service principal on the shared core (P0.1). Admin only. The returned definition’s secret is never re-exported; callers must retain the raw secret they supplied.

pub fn revoke_service_principal(&self, token_id: &str) -> Result<()>

Revoke a registered service principal. Admin only. Existing handles bound to the token fail on the next authorized operation.

pub fn set_service_principal_permissions( &self, token_id: &str, permissions: Vec<Permission>, ) -> Result<()>

Replace the live permission set for a registered service principal. Admin only. Scope reduction takes effect on the next authorize without reopening handles.

pub fn shutdown(&self, drain_deadline: Duration) -> Result<()>

Shut the shared core down (spec §10.1, S1A-004): drain in-flight operations within drain_deadline, sync durable state, release the file lock, and mark the core Closed. Every handle — including this one — then rejects further operations. Dropping a handle never closes storage; only this method or the last core drop does.

Trait Implementations

impl Debug for DatabaseHandle

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

Formats the value using the given formatter.