Struct DbSession 

pub struct DbSession<C: CanisterKind> { /* private fields */ }

DbSession

Public facade for session-scoped query execution, typed SQL lowering, and structural mutation policy. Wraps the core session and converts core results and errors into the outward-facing icydb response surface.

Implementations

impl<C: CanisterKind> DbSession<C>

pub const fn new(session: DbSession<C>) -> Self

pub const fn debug(self) -> Self

pub fn metrics_sink(self, sink: &'static dyn MetricsSink) -> Self

pub const fn load<E>(&self) -> FluentLoadQuery<'_, E>

where E: PersistedRow<Canister = C>,

pub const fn load_with_consistency<E>( &self, consistency: MissingRowPolicy, ) -> FluentLoadQuery<'_, E>

where E: PersistedRow<Canister = C>,

pub fn execute_sql_query<E>(&self, sql: &str) -> Result<SqlQueryResult, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Execute one reduced SQL query against one concrete entity type.

pub fn execute_sql_update<E>(&self, sql: &str) -> Result<SqlQueryResult, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Execute one reduced SQL mutation statement against one concrete entity type.

pub fn delete<E>(&self) -> SessionDeleteQuery<'_, E>

where E: PersistedRow<Canister = C>,

pub fn delete_with_consistency<E>( &self, consistency: MissingRowPolicy, ) -> SessionDeleteQuery<'_, E>

where E: PersistedRow<Canister = C>,

pub fn show_indexes<E>(&self) -> Vec<String>

where E: EntityKind<Canister = C>,

Return one stable, human-readable index listing for the entity schema.

pub fn show_columns<E>(&self) -> Vec<EntityFieldDescription>

where E: EntityKind<Canister = C>,

Return one stable list of field descriptors for the entity schema.

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

Return one stable list of runtime-registered entity names.

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

Return one stable list of runtime-registered entity names.

This is the typed alias of SQL SHOW TABLES, which itself aliases SHOW ENTITIES.

pub fn describe_entity<E>(&self) -> EntitySchemaDescription

where E: EntityKind<Canister = C>,

Return one structured schema description for the entity.

pub fn storage_report( &self, name_to_path: &[(&'static str, &'static str)], ) -> Result<StorageReport, Error>

Build one point-in-time storage report for observability endpoints.

pub fn execute_query<E>( &self, query: &Query<E>, ) -> Result<QueryResponse<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

pub fn trace_query<E>(&self, query: &Query<E>) -> Result<QueryTracePlan, Error>

where E: EntityKind<Canister = C>,

Build one trace payload for a query without executing it.

pub fn insert<E>(&self, entity: E) -> Result<E, Error>

where E: PersistedRow<Canister = C> + EntityValue,

pub fn insert_returning_all<E>( &self, entity: E, ) -> Result<SqlQueryRowsOutput, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Insert one full entity and return every persisted field.

pub fn insert_returning<E, I, S>( &self, entity: E, fields: I, ) -> Result<SqlQueryRowsOutput, Error>

where E: PersistedRow<Canister = C> + EntityValue, I: IntoIterator<Item = S>, S: AsRef<str>,

Insert one full entity and return one explicit field list.

pub fn create<I>(&self, input: I) -> Result<I::Entity, Error>

where I: EntityCreateInput, I::Entity: PersistedRow<Canister = C> + EntityValue,

Create one authored typed input.

pub fn create_returning_all<I>( &self, input: I, ) -> Result<SqlQueryRowsOutput, Error>

where I: EntityCreateInput, I::Entity: PersistedRow<Canister = C> + EntityValue,

Create one authored typed input and return every persisted field.

pub fn create_returning<I, F, S>( &self, input: I, fields: F, ) -> Result<SqlQueryRowsOutput, Error>

where I: EntityCreateInput, I::Entity: PersistedRow<Canister = C> + EntityValue, F: IntoIterator<Item = S>, S: AsRef<str>,

Create one authored typed input and return one explicit field list.

pub fn insert_many_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Insert a single-entity-type batch atomically in one commit window.

If any item fails pre-commit validation, no row in the batch is persisted.

This API is not a multi-entity transaction surface.

pub fn insert_many_non_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Insert a batch with explicitly non-atomic semantics.

WARNING: fail-fast and non-atomic. Earlier inserts may commit before an error.

pub fn replace<E>(&self, entity: E) -> Result<E, Error>

where E: PersistedRow<Canister = C> + EntityValue,

pub fn replace_many_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Replace a single-entity-type batch atomically in one commit window.

If any item fails pre-commit validation, no row in the batch is persisted.

This API is not a multi-entity transaction surface.

pub fn replace_many_non_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Replace a batch with explicitly non-atomic semantics.

WARNING: fail-fast and non-atomic. Earlier replaces may commit before an error.

pub fn update<E>(&self, entity: E) -> Result<E, Error>

where E: PersistedRow<Canister = C> + EntityValue,

pub fn update_returning_all<E>( &self, entity: E, ) -> Result<SqlQueryRowsOutput, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Update one full entity and return every persisted field.

pub fn update_returning<E, I, S>( &self, entity: E, fields: I, ) -> Result<SqlQueryRowsOutput, Error>

where E: PersistedRow<Canister = C> + EntityValue, I: IntoIterator<Item = S>, S: AsRef<str>,

Update one full entity and return one explicit field list.

pub fn mutate_structural<E>( &self, key: E::Key, patch: StructuralPatch, mode: MutationMode, ) -> Result<E, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Apply one structural mutation under one explicit write-mode contract.

This is a dynamic, field-name-driven write ingress, not a weaker write path: the same entity validation and commit rules still apply before the write can succeed.

mode semantics are explicit:

• Insert: sparse patches are allowed; missing fields must materialize through explicit defaults or managed-field preflight, and the write still fails if the row already exists.
• Update: patch applies over the existing row; fails if the row is missing.
• Replace: sparse patches are allowed, but omitted fields are not inherited from the previous value; they must materialize through explicit defaults or managed-field preflight, and the row is inserted if it is missing.

pub fn structural_patch<E, I, S>( &self, fields: I, ) -> Result<StructuralPatch, Error>

where E: PersistedRow<Canister = C> + EntityValue, I: IntoIterator<Item = (S, InputValue)>, S: AsRef<str>,

Build one structural mutation patch through the active accepted schema.

This session-owned constructor resolves field names through persisted schema metadata before returning the patch to the caller.

pub fn update_many_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Update a single-entity-type batch atomically in one commit window.

If any item fails pre-commit validation, no row in the batch is persisted.

This API is not a multi-entity transaction surface.

pub fn update_many_non_atomic<E>( &self, entities: impl IntoIterator<Item = E>, ) -> Result<Vec<E>, Error>

where E: PersistedRow<Canister = C> + EntityValue,

Update a batch with explicitly non-atomic semantics.

WARNING: fail-fast and non-atomic. Earlier updates may commit before an error.