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

icydb_core/db/session/
mod.rs
