icydb_core/db/session/
mod.rs

1//! Module: session
2//! Responsibility: user-facing query/write execution facade over db executors.
3//! Does not own: planning semantics, cursor validation rules, or storage mutation protocol.
4//! Boundary: converts fluent/query intent calls into executor operations and response DTOs.
5
6mod accepted_schema;
7mod bounded_cache;
8mod catalog;
9mod integrity;
10mod query;
11mod response;
12#[cfg(feature = "sql")]
13mod sql;
14mod write;
15
16#[cfg(all(test, feature = "sql", feature = "diagnostics"))]
17mod tests;
18
19use crate::metrics::sink::with_metrics_sink;
20use crate::{
21    db::{Db, StoreRegistry},
22    metrics::sink::MetricsSink,
23    traits::CanisterKind,
24};
25use std::thread::LocalKey;
26
27pub(in crate::db) use accepted_schema::AcceptedSchemaCatalogContext;
28#[cfg(all(feature = "sql", feature = "diagnostics"))]
29pub use query::{
30    DirectDataRowAttribution, GroupedCountAttribution, GroupedExecutionAttribution,
31    KernelRowAttribution, ScalarAggregateAttribution,
32};
33pub(in crate::db) use response::finalize_structural_grouped_projection_result;
34pub(in crate::db) use response::grouped_cursor_from_bytes;
35#[cfg(all(feature = "sql", feature = "diagnostics"))]
36pub use sql::{
37    SqlCompileAttribution, SqlExecutionAttribution, SqlHybridCoveringAttribution,
38    SqlOutputBlobAttribution, SqlPureCoveringAttribution, SqlQueryCacheAttribution,
39    SqlQueryExecutionAttribution,
40};
41#[cfg(feature = "sql")]
42pub use sql::{
43    SqlConstraintValidationPage, SqlConstraintValidationRevisionStatus,
44    SqlConstraintValidationState, SqlDdlExecutionStatus, SqlDdlMutationKind,
45    SqlDdlPreparationReport, SqlIntegrityError, SqlStatementDispatch, SqlStatementResult,
46    SqlStatementShellSurface, SqlStatementSurface, TrustedResumableUpdateContinuation,
47    TrustedResumableUpdatePhase, TrustedResumableUpdateReceipt,
48    TrustedResumableUpdateRestartReason, sql_statement_dispatch, sql_statement_entity_name,
49    sql_statement_shell_surface, sql_statement_surface,
50};
51#[cfg(feature = "sql")]
52pub(in crate::db::session) use write::{
53    AcceptedStructuralMutation, AcceptedStructuralMutationTarget,
54    structural_data_key_from_runtime_values,
55};
56
57///
58/// DbSession
59///
60/// Session-scoped database handle with policy (debug, metrics) and execution routing.
61///
62
63pub struct DbSession<C: CanisterKind> {
64    db: Db<C>,
65    debug: bool,
66    metrics: Option<&'static dyn MetricsSink>,
67}
68
69impl<C: CanisterKind> DbSession<C> {
70    /// Construct one session facade over a sealed runtime store registry.
71    #[must_use]
72    pub const fn new(store: &'static LocalKey<StoreRegistry>) -> Self {
73        Self {
74            db: Db::new(store),
75            debug: false,
76            metrics: None,
77        }
78    }
79
80    /// Enable debug execution behavior where supported by executors.
81    #[must_use]
82    pub const fn debug(mut self) -> Self {
83        self.debug = true;
84        self
85    }
86
87    /// Attach one metrics sink for all session-executed operations.
88    #[must_use]
89    pub const fn metrics_sink(mut self, sink: &'static dyn MetricsSink) -> Self {
90        self.metrics = Some(sink);
91        self
92    }
93
94    fn with_metrics<T>(&self, f: impl FnOnce() -> T) -> T {
95        if let Some(sink) = self.metrics {
96            with_metrics_sink(sink, f)
97        } else {
98            f()
99        }
100    }
101}
icydb_core/db/session/mod.rs

icydb_core/db/session/
mod.rs
