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: 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.

impl<C: CanisterKind> DbSession<C>

pub fn sql_statement_route( &self, sql: &str, ) -> Result<SqlStatementRoute, QueryError>

Parse one reduced SQL statement into canonical routing metadata.

This method is the SQL dispatch authority for entity/surface routing outside typed-entity lowering paths.

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

where E: EntityKind<Canister = C>,

Execute one reduced SQL DESCRIBE statement for entity E.

pub fn show_indexes_sql<E>(&self, sql: &str) -> Result<Vec<String>, QueryError>

where E: EntityKind<Canister = C>,

Execute one reduced SQL SHOW INDEXES statement for entity E.

pub fn show_entities_sql(&self, sql: &str) -> Result<Vec<String>, QueryError>

Execute one reduced SQL SHOW ENTITIES statement.

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

where E: EntityKind<Canister = C>,

Build one typed query intent from one reduced SQL statement.

This parser/lowering entrypoint is intentionally constrained to the executable subset wired in the current release.

pub fn sql_projection_columns<E>( &self, sql: &str, ) -> Result<Vec<String>, QueryError>

where E: EntityKind<Canister = C>,

Derive canonical projection column labels for one reduced SQL SELECT statement.

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

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

Execute one reduced SQL SELECT/DELETE statement for entity E.

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

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

Execute one reduced SQL SELECT statement and return projection-shaped rows.

This surface keeps execute_sql(...) stable for callers that consume full entity rows.

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

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

Execute one reduced SQL global aggregate SELECT statement.

This entrypoint is intentionally constrained to one aggregate terminal shape per statement and preserves existing terminal semantics.

pub fn execute_sql_grouped<E>( &self, sql: &str, cursor_token: Option<&str>, ) -> Result<PagedGroupedExecutionWithTrace, QueryError>

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

Execute one reduced SQL grouped SELECT statement and return grouped rows.

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

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

Explain one reduced SQL statement for entity E.

Supported modes:

• EXPLAIN ... -> logical plan text
• EXPLAIN EXECUTION ... -> execution descriptor text
• EXPLAIN JSON ... -> logical plan canonical JSON

impl<C: CanisterKind> DbSession<C>

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.

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 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_entities(&self) -> Vec<String>

Return one stable list of runtime-registered entity names.

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 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 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.