Struct DbSession 

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

DbSession

Session-scoped database handle with policy (debug, metrics) and execution routing.

Implementations

impl<C: CanisterKind> DbSession<C>

pub const fn new_with_hooks( store: &'static LocalKey<StoreRegistry>, entity_runtime_hooks: &'static [EntityRuntimeHooks<C>], ) -> Self

Construct one session facade from store registry and runtime hooks.

pub const fn debug(self) -> Self

Enable debug execution behavior where supported by executors.

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

Attach one metrics sink for all session-executed operations.

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

where E: EntityKind<Canister = C>,

Start a fluent load query with default missing-row policy (Ignore).

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

where E: EntityKind<Canister = C>,

Start a fluent load query with explicit missing-row policy.

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

where E: EntityKind<Canister = C>,

Start a fluent delete query with default missing-row policy (Ignore).

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

where E: EntityKind<Canister = C>,

Start a fluent delete query with explicit missing-row policy.

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

where E: EntityKind<Canister = C>,

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

Output format mirrors SQL-style introspection:

• PRIMARY KEY (field)
• INDEX name (field_a, field_b)
• UNIQUE INDEX name (field_a, field_b)

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

where E: EntityKind<Canister = C>,

Return one structured schema description for the entity.

This is a typed DESCRIBE-style introspection surface consumed by developer tooling and pre-EXPLAIN debugging.

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

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

Execute one scalar load/delete query and return materialized response rows.

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

where E: EntityKind<Canister = C>,

Build one trace payload for a query without executing it.

This lightweight surface is intended for developer diagnostics: plan hash, access strategy summary, and planner/executor route shape.

pub fn execute_grouped<E>( &self, query: &Query<E>, cursor_token: Option<&str>, ) -> Result<PagedGroupedExecutionWithTrace, QueryError>

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

Execute one grouped query page with optional grouped continuation cursor.

This is the explicit grouped execution boundary; scalar load APIs reject grouped plans to preserve scalar response contracts.

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

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

Insert one entity row.

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

where E: EntityKind<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<WriteBatchResponse<E>, InternalError>

where E: EntityKind<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, InternalError>

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

Replace one existing entity row.

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

where E: EntityKind<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<WriteBatchResponse<E>, InternalError>

where E: EntityKind<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, InternalError>

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

Update one existing entity row.

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

where E: EntityKind<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<WriteBatchResponse<E>, InternalError>

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

Update a batch with explicitly non-atomic semantics.

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

pub fn insert_view<E>( &self, view: E::ViewType, ) -> Result<E::ViewType, InternalError>

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

Insert one view value and return the stored view.

pub fn replace_view<E>( &self, view: E::ViewType, ) -> Result<E::ViewType, InternalError>

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

Replace one view value and return the stored view.

pub fn update_view<E>( &self, view: E::ViewType, ) -> Result<E::ViewType, InternalError>

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

Update one view value and return the stored view.