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 fn execute_query<E>( &self, query: &Query<E>, ) -> Result<EntityResponse<E>, QueryError>

where E: PersistedRow<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.

impl<C: CanisterKind> DbSession<C>

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

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

Execute one single-entity reduced SQL query or introspection statement.

This surface stays hard-bound to E, rejects state-changing SQL, and returns SQL-shaped statement output instead of typed entities.

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

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

Execute one single-entity reduced SQL mutation statement.

This surface stays hard-bound to E, rejects read-only SQL, and returns SQL-shaped mutation output such as counts or RETURNING rows.

impl<C: CanisterKind> DbSession<C>

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

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

Insert one entity row.

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

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

Insert one authored typed input.

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

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

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, InternalError>

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

Replace one existing entity row.

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

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

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

This is the public core session boundary for structural writes: callers provide the key, field patch, and intended mutation mode, and the session routes that through the shared structural mutation pipeline.

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

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

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, InternalError>

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

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.

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: PersistedRow<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: PersistedRow<Canister = C>,

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

pub const fn select_one(&self) -> Value

Return one constant scalar row equivalent to SQL SELECT 1.

This terminal bypasses query planning and access routing entirely.

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 show_indexes_for_model(&self, model: &'static EntityModel) -> Vec<String>

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

This model-only helper is schema-owned and intentionally does not attach runtime lifecycle state because it does not carry store placement context.

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_columns_for_model( &self, model: &'static EntityModel, ) -> Vec<EntityFieldDescription>

Return one stable list of field descriptors for one schema model.

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.

SHOW TABLES is only an alias for SHOW ENTITIES, so the typed metadata surface keeps the same alias relationship.

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 describe_entity_model( &self, model: &'static EntityModel, ) -> EntitySchemaDescription

Return one structured schema description for one schema model.

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

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

pub fn storage_report_default(&self) -> Result<StorageReport, InternalError>

Build one point-in-time storage report using default entity-path labels.

pub fn integrity_report(&self) -> Result<IntegrityReport, InternalError>

Build one point-in-time integrity scan report for observability endpoints.

pub fn execute_migration_plan( &self, plan: &MigrationPlan, max_steps: usize, ) -> Result<MigrationRunOutcome, InternalError>

Execute one bounded migration run with durable internal cursor state.

Migration progress is persisted internally so upgrades/restarts can resume from the last successful step without external cursor ownership.