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

icydb_core/db/session/
mod.rs
