laminar_db/
lib.rs

1//! Unified database facade for `LaminarDB`.
2//!
3//! Provides a single entry point (`LaminarDB`) that ties together
4//! the SQL parser, query planner, `DataFusion` context, and streaming API.
5//!
6//! # Example
7//!
8//! ```rust,ignore
9//! use laminar_db::LaminarDB;
10//!
11//! let db = LaminarDB::open()?;
12//!
13//! db.execute("CREATE SOURCE trades (
14//!     symbol VARCHAR, price DOUBLE, ts TIMESTAMP,
15//!     WATERMARK FOR ts AS ts - INTERVAL '1' SECOND
16//! )").await?;
17//!
18//! let query = db.execute("SELECT symbol, AVG(price)
19//!     FROM trades GROUP BY symbol, TUMBLE(ts, INTERVAL '1' MINUTE)
20//! ").await?;
21//! ```
22
23#![deny(missing_docs)]
24#![warn(clippy::all, clippy::pedantic)]
25#![allow(clippy::duration_suboptimal_units)] // MSRV 1.85; from_mins/from_hours are 1.91+
26#![allow(clippy::module_name_repetitions)]
27#![allow(clippy::too_many_arguments, clippy::too_many_lines)] // Lifecycle protocols remain contiguous and keep fencing inputs explicit.
28#![allow(clippy::disallowed_types)] // Control-plane maps mirror persisted and cross-crate checkpoint types.
29#![allow(clippy::unused_self)]
30// Feature stubs preserve shared protocol call sites.
31// Lifecycle fixtures favor explicit protocol setup and boundary assertions.
32#![cfg_attr(
33    test,
34    allow(
35        clippy::assert_is_empty, // Assert cardinality without requiring equality on fixture elements.
36        clippy::assertions_on_constants,
37        clippy::default_trait_access,
38        clippy::field_reassign_with_default,
39        clippy::filter_map_bool_then,
40        clippy::float_cmp,
41        clippy::items_after_statements,
42        clippy::manual_let_else,
43        clippy::match_wildcard_for_single_variants,
44        clippy::needless_borrow,
45        clippy::needless_pass_by_value,
46        clippy::needless_return,
47        clippy::redundant_closure,
48        clippy::similar_names,
49        clippy::single_char_pattern,
50        clippy::type_complexity,
51        clippy::unchecked_time_subtraction,
52        clippy::unnecessary_to_owned,
53        clippy::unnecessary_wraps,
54        clippy::unnested_or_patterns,
55        clippy::used_underscore_binding
56    )
57)]
58
59mod aggregate_state;
60/// AI inference module, containing model registry, provider trait, and backends.
61pub mod ai;
62mod ai_catalog;
63mod ai_worker;
64mod builder;
65mod catalog;
66mod catalog_connector;
67mod changelog_filter;
68/// Unified checkpoint coordination.
69#[doc(hidden)]
70pub mod checkpoint_coordinator;
71/// Bounded process-local evidence for cluster checkpoint barrier pauses.
72#[cfg(feature = "cluster")]
73pub mod checkpoint_timing;
74mod config;
75mod connector_manager;
76mod connector_task_fence;
77#[cfg(feature = "cluster")]
78mod coordinated_recovery;
79mod core_window_state;
80mod db;
81/// Prometheus metrics for the streaming engine.
82pub mod engine_metrics;
83mod flow_metrics;
84// Reopened `impl LaminarDB` modules — split from db.rs
85/// FFI-friendly API for language bindings.
86///
87/// Enable with the `api` feature flag:
88/// ```toml
89/// laminar-db = { version = "0.1", features = ["api"] }
90/// ```
91///
92/// This module provides thread-safe types with numeric error codes,
93/// explicit resource management, and Arrow RecordBatch at all boundaries.
94#[cfg(feature = "api")]
95pub mod api;
96mod ddl;
97mod direct_mutation;
98mod error;
99mod exchange_plan;
100mod filter_compile;
101mod handle;
102mod interval_join;
103mod key_column;
104mod log_throttle;
105mod memory_budget;
106mod metrics;
107mod metrics_api;
108mod mv_store;
109mod operator;
110mod operator_graph;
111/// Thread-per-core connector pipeline.
112pub mod pipeline;
113mod pipeline_callback;
114mod pipeline_identity;
115mod pipeline_lifecycle;
116pub mod process_function;
117/// Deployment profiles.
118pub mod profile;
119mod query_rows;
120/// Dynamic vnode rebalance control plane.
121#[cfg(feature = "cluster")]
122pub mod rebalance;
123/// Unified recovery manager.
124pub mod recovery_manager;
125mod show_commands;
126mod sink_task;
127mod sql_analysis;
128mod sql_utils;
129/// External named-subscription substrate: byte-bounded shared logs and cursor portals.
130pub mod subscription;
131mod table_provider;
132mod table_rows;
133mod table_store;
134
135#[cfg(feature = "benchmark-internals")]
136#[doc(hidden)]
137pub use table_store::benchmark::ReferenceTableBenchmark;
138
139#[cfg(feature = "benchmark-internals")]
140#[doc(hidden)]
141pub use aggregate_state::benchmark::AggregateBenchmark;
142
143#[cfg(feature = "benchmark-internals")]
144#[doc(hidden)]
145pub use operator::benchmark::{ClusterAggregateBenchmark, IntervalJoinBenchmark};
146
147#[cfg(feature = "benchmark-internals")]
148#[doc(hidden)]
149pub use mv_store::benchmark::{MaterializedViewBenchmark, MaterializedViewBenchmarkMode};
150#[cfg(all(test, feature = "cluster"))]
151mod cluster_conformance;
152#[cfg(all(test, feature = "cluster"))]
153mod cluster_test_support;
154mod temporal_join_state;
155#[cfg(test)]
156mod temporal_test_source;
157#[cfg(feature = "cluster")]
158mod vnode_load;
159#[cfg(feature = "cluster")]
160mod vnode_transition_staging;
161
162// End-to-end tests for the crypto-sentiment demo pipeline, backed by wiremock.
163// In-crate (not tests/) so it can drive the OperatorGraph directly.
164#[cfg(test)]
165mod e2e_crypto_sentiment;
166
167/// C FFI layer for LaminarDB.
168///
169/// Enable with the `ffi` feature flag:
170/// ```toml
171/// laminar-db = { version = "0.1", features = ["ffi"] }
172/// ```
173///
174/// This module provides `extern "C"` functions for calling LaminarDB from C
175/// and any language with C FFI support (Python, Java, Node.js, .NET, etc.).
176#[cfg(feature = "ffi")]
177pub mod ffi;
178
179pub use builder::LaminarDbBuilder;
180pub use catalog::{ArrowRecord, SourceCatalog, SourceEntry};
181pub use checkpoint_coordinator::{
182    CheckpointFailureDisposition, CheckpointPhase, CheckpointResult, CheckpointStats,
183};
184pub use config::{
185    validate_managed_state_max_bytes, validate_materialized_view_limits,
186    validate_reference_table_limits, validate_source_queue_max_bytes, BackpressurePolicy,
187    LaminarConfig, RestartPolicy, DEFAULT_DATAFUSION_MEMORY_LIMIT_BYTES,
188    DEFAULT_MATERIALIZED_VIEW_MAX_BYTES, DEFAULT_MATERIALIZED_VIEW_MAX_ROWS,
189    DEFAULT_MATERIALIZED_VIEW_READ_CACHE_BYTES, DEFAULT_MAX_MANAGED_STATE_BYTES,
190    DEFAULT_REFERENCE_TABLE_MAX_BYTES, DEFAULT_REFERENCE_TABLE_MAX_ROWS,
191    DEFAULT_SOURCE_QUEUE_MAX_BYTES, MAX_SOURCE_QUEUE_BYTES,
192};
193pub use db::committed_read::CommittedQuery;
194pub use db::read_level::{ReadLevel, ReadResult};
195pub use db::LaminarDB;
196pub use engine_metrics::EngineMetrics;
197pub use error::DbError;
198pub use handle::{
199    DdlInfo, ExecuteResult, FromBatch, MaterializedViewInfo, PipelineEdge, PipelineNode,
200    PipelineNodeType, PipelineTopology, QueryHandle, QueryInfo, SinkInfo, SourceHandle, SourceInfo,
201    StreamInfo, SubscriptionError, TypedSubscription, TypedSubscriptionEnvelope,
202    TypedSubscriptionFrame, UntypedSourceHandle,
203};
204pub use laminar_connectors::connector::DeliveryGuarantee;
205pub use metrics::{PipelineMetrics, PipelineState, SourceMetrics, StreamMetrics};
206pub use mv_store::{CommittedRead, CommittedReadError, ReadCut};
207pub use profile::{Profile, ProfileError};
208pub use query_rows::QueryRows;
209pub use recovery_manager::{RecoveredState, RecoveryManager};
210pub use subscription::ClusterSubscriptionError;
211
212/// Criterion-only access to the real committed cluster-subscription gateway.
213#[cfg(feature = "benchmark-internals")]
214#[doc(hidden)]
215pub use subscription::cluster::benchmark::{
216    ClusterSubscriptionGatewayBenchmark, GatewayReplayObservation, SlowReaderFootprint,
217};
218
219/// Cluster assignment lifecycle results.
220#[cfg(feature = "cluster")]
221pub use db::{ClusterStartupDisposition, SnapshotAdoption};
222#[cfg(feature = "cluster")]
223pub use db::{
224    ClusterTopologyAdoptionRequest, ClusterTopologyRequest, ClusterTopologyStatus,
225    PreparedTopologyRestore, PreparedTopologySourcePosition,
226};
227#[cfg(feature = "cluster")]
228pub use db::{
229    ClusterTopologyObjectPlan, ClusterTopologyObjectTransition, ClusterTopologyValidation,
230    TopologyActivationRequirement, TopologyInitialization, TopologyValidationScope,
231};
232/// Per-vnode state of keyed operators, live and at the committed checkpoint.
233#[cfg(feature = "cluster")]
234pub use vnode_load::{
235    CommittedVnodeFrame, LiveVnodeLoad, OperatorVnodeLoad, VnodeLoadCheckpoint, VnodeLoadEntry,
236    VnodeLoadReport,
237};
238
239/// Re-export the connector registry for custom connector registration.
240pub use laminar_connectors::registry::ConnectorRegistry;
241
242/// Re-export connector metadata types for the control-plane HTTP API
243/// (connector catalog / source-creation wizard).
244pub use laminar_connectors::config::{ConfigKeySpec, ConnectorInfo};
laminar_db/lib.rs

laminar_db/
lib.rs
