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

icydb_core/db/session/
mod.rs
