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

icydb_core/db/session/
mod.rs
