Struct LaminarDB 

pub struct LaminarDB { /* private fields */ }

The main LaminarDB database handle.

Unified interface for SQL execution, data ingestion, and result consumption.

Implementations

impl LaminarDB

pub async fn execute_cluster_bootstrap_batch( &self, sql: &[String], ) -> Result<Vec<ExecuteResult>, DbError>

Resolve, validate and durably seal the complete startup catalog before activation. Existing sealed catalogs accept their unchanged original definitions without discovery.

Errors

Rejects divergent definitions, unsupported plans, stale leader authority and failed sealing. Authorized external preparation may leave unused artifacts if publication fails.

impl LaminarDB

pub async fn query_committed( &self, sql: &str, at: CommittedRead, ) -> Result<CommittedQuery, DbError>

Run the query sql with every materialized view it scans read at the one committed checkpoint at resolves to.

The result never mixes checkpoints and is never rolled back, and a later CommittedRead::Latest read on this database never sees an earlier epoch. It is as fresh as the checkpoint cadence. Pass a returned epoch back as CommittedRead::AtLeast to read no earlier than a previous result. CommittedRead::Recent waits until the newest cut holds every record the views’ sources had upstream when the read arrived, so a client reads what it wrote to a source; every source behind the views must report its upstream position (reference tables are looked up and are not waited for). An append view with a row-count retention is not exact: which rows a cap keeps depends on arrival order.

The statement may scan only materialized views. The checkpoint is held against retention for at most 30 seconds, which bounds the read, including any wait for CommittedRead::AtLeast or CommittedRead::Recent. A cluster node reads every participant’s committed state, so any node serves any view; it reads only cuts at or after the durable pin it holds. A node outside the checkpoint participants (draining, or not yet assigned) learns of each cut of its own topology from the cluster authority within about a second.

Errors

DbError::CommittedRead when checkpointing is disabled, the requested epoch has not committed in time or is no longer retained, the statement scans live state, a recent read’s source cannot report or failed to report its upstream position, or the read passes its deadline; any planning or execution error of sql.

impl LaminarDB

pub fn default_read_level(&self) -> ReadLevel

The level a read uses when its session chose none: ReadLevel::Latest in embedded and single-node mode, the newest committed checkpoint on a cluster node.

pub async fn read( &self, sql: &str, level: ReadLevel, ) -> Result<ReadResult, DbError>

Run the query sql with every materialized view it scans read at level.

Each table is read as a snapshot, so joins between views, sources and reference tables are bounded. A committed read loads its views before this returns and holds its checkpoint against retention until then; the rows then stream to the reader as it reads them.

Errors

DbError::InvalidOperation if sql is not one query or reads a view at ReadLevel::Latest on a cluster node; the errors of Self::query_committed for a committed read; any planning or execution error of sql.

pub async fn read_schema( &self, sql: &str, ) -> Result<(SchemaRef, usize), DbError>

The schema of the rows Self::read returns for sql and the parameter count it declares, planned without reading any table.

Errors

DbError::InvalidOperation if sql is not one query; any planning error of sql.

impl LaminarDB

pub async fn certify_installed_cluster_topology( self: &Arc<Self>, operation: TopologyOperationId, ) -> Result<TopologyAdmissionStatus, DbError>

Certify this process’s exact installed runtime while intake remains held. The DB-owned executor continues after caller disconnect. This receipt alone never authorizes output.

Errors

Rejects absent/dead actors, stale process/assignment/transport, faults or uncertain writes.

pub async fn release_installed_cluster_topology( self: &Arc<Self>, operation: TopologyOperationId, ) -> Result<TopologyAdmissionStatus, DbError>

As the current leader, publish participant-complete Release and apply it locally. Each follower must separately apply the same durable Release against its own runtime receipt. A committed Release remains authoritative if local activation fails; intake stays held.

Errors

Rejects incomplete/currently stale rosters, leader loss, local runtime failure or the budget.

pub async fn apply_cluster_topology_release( self: &Arc<Self>, operation: TopologyOperationId, ) -> Result<TopologyAdmissionStatus, DbError>

Apply the authoritative Release to this exact runtime. Reconcile/admit sink epochs through the existing coordinator before opening intake. Caller cancellation never owns that work.

Errors

Rejects missing Release, another runtime’s receipt, stale authority or unresolved sink work.

impl LaminarDB

pub async fn commit_cluster_topology_target( &self, image: &mut PreparedTopologyRestore, ) -> Result<TopologyAdmissionStatus, DbError>

Irreversibly commit this DB’s retained target image after complete protocol-four preparation. The configured leader supplies all authority/process/assignment fences. The target catalog and exact root share one append; target actors, output and intake stay fenced.

The total cooperative budget is 45 seconds, including observed retirement and final reads. A cancelled/uncertain append can have committed. Retrying the same image resolves the same decision; after image loss use recover_committed_cluster_topology, never parent rollback.

Errors

Rejects foreign/stale images, incomplete participant capabilities, local faults or unresolved authority. Commit alone grants no installation or output permission; runtime DDL remains guarded until automatic target recovery is certified.

impl LaminarDB

pub async fn install_committed_cluster_topology( self: &Arc<Self>, image: PreparedTopologyRestore, ) -> Result<(), DbError>

Install the exact committed catalog, restored graph and connector actors with intake held. The existing startup owner outlives caller cancellation. No target checkpoint, source acknowledgement, readiness receipt, external epoch admission or Release is invented. Success means the local control loop is installed, never that the topology is active.

Errors

Rejects foreign/uncommitted/executed images, stale authority, unresolved predecessor work, unsupported atomic source starts, local faults and the 45-second installation budget. Failed installation retains Commit, the catalog and namespace ownership for root recovery.

impl LaminarDB

pub async fn stage_cluster_topology_migration_root( &self, operation_id: TopologyOperationId, ) -> Result<TopologyAdmissionStatus, DbError>

Durably stage preserved state/progress and source initialization for a prepared addition. Requires the current leader’s running parent and held cut. The configured checkpoint reader supplies metadata only; no state is copied or restored and no target actor starts. New sources use their configured connector’s read-only initialization contract. The first sealed global cursor survives a disconnect before publication and is never resolved again. Built-in Kafka supports explicit topics with earliest/latest; other connectors fail closed.

Errors

Rejects a missing held cut, shutdown/recovery/leader/process fences, damaged metadata, unsupported initialization or a 30 second total deadline (authority publication is bounded to 15 seconds/16 CAS attempts). A cancelled caller may have durably staged the root; query operation status or retry the same operation identity.

impl LaminarDB

pub async fn validate_cluster_topology_change( &self, expected_parent: TopologyVersion, statements: &[String], ) -> Result<ClusterTopologyValidation, DbError>

Compile a topology candidate separately from the active graph.

Each entry is one typed CREATE, CREATE OR REPLACE or DROP SOURCE/STREAM/SINK without CASCADE. Replacement preserves compatible state by default. Ordered DROP/CREATE explicitly resets the affected objects to future-only input under new incarnations; reset dependents first. Supports replayable sources, supported managed/stateless streams and durable sinks while proving unchanged definitions remain compatible. New managed state starts empty at the cut; input that can retract an unavailable prefix is rejected. No source is opened or polled, no sink is opened or published, and no authority/checkpoint ID is written. A successful response does not authorize SQL submission, restore or target activation.

One compiler per process, 64 statements/256 KiB input, 256 parent/target object mappings, a 1 MiB descriptor and a 30 second end-to-end deadline bound control-path resource use.

Errors

Rejects parent conflicts, unsupported mutations, uncertified execution or connector contracts, divergent local definitions, malformed input and exceeded bounds.

impl LaminarDB

pub async fn prepare_cluster_topology_operation( &self, operation_id: TopologyOperationId, ) -> Result<TopologyAdmissionStatus, DbError>

Independently compile and durably certify an already admitted operation on this process. This neither submits a mutation nor closes intake, restores state or authorizes target output. The exact target and descriptor come from immutable shared authority, never the caller. A disconnect may leave a successful certificate; query status or retry the same operation.

Errors

Requires Running state, live process/assignment authority, an adopted exact parent and a matching compiled candidate. One existing compiler slot and a 45 second end-to-end deadline bound read/compile/publication; publication retains the authority’s 15 second/16-CAS bounds.

impl LaminarDB

pub async fn prepare_cluster_topology_recovery( &self, operation_id: TopologyOperationId, ) -> Result<PreparedTopologyRestore, DbError>

Build one unstarted recovery image from the greatest exact target checkpoint, or the explicitly mapped root when no target checkpoint has committed. State, source cursors and subscription frontiers come from the same selected cut. The existing compiler owns the image, and verified encoded state is released immediately after decoding.

This changes no live catalog, transport, actors or output. A recovery image cannot use original migration installation/Release APIs; coordinated recovery authorization is required.

Errors

Rejects live/faulted local actors, obsolete targets, changed ownership/process adoption, damaged state/output, missing source progress and configured read/state/deadline limits.

impl LaminarDB

pub async fn prepare_cluster_topology_restore( &self, operation_id: TopologyOperationId, ) -> Result<PreparedTopologyRestore, DbError>

Restore one private target from the exact held and authority-bound old cut. Replays the immutable candidate, checks its complete certified descriptor, loads verified local state through the strict parent recovery path, and preserves subscription incarnations and exclusive sequences. Sealed source cursors are validated without resolving them again. This neither mutates the live catalog/coordinator nor installs actors or opens intake.

One image owns the existing compiler slot for its lifetime. The 45 second request budget, aggregate 16 MiB manifest limit, configured node-read and managed-state budgets bound restore. Cancellation/error drops the partial image and releases the slot, retaining the parent hold.

Errors

Rejects absent holds, stale full-roster/process/assignment authority, divergent compilation, damaged state/output artifacts, missing state or subscription frontiers and exceeded bounds.

pub async fn recover_committed_cluster_topology( &self, operation_id: TopologyOperationId, ) -> Result<PreparedTopologyRestore, DbError>

Reconstruct the current committed target from its exact migration root before its first checkpoint. Reuses the same strict historical-parent loader and actual target codecs. A Created DB or still-held retired parent can reconstruct; the private image never starts actors, changes the local catalog/coordinator, acknowledges input or opens intake.

Errors

Rejects uncommitted/obsolete targets, live or faulted local actors, changed owner maps, stale current process/adoption, missing/corrupt artifacts or the existing 45 second budget.

impl LaminarDB

pub async fn retire_cluster_topology_parent( &self, image: &mut PreparedTopologyRestore, ) -> Result<(), DbError>

Retire the old actors for this database’s privately restored exact-root target.

Revalidates the full current preparation roster, leader, process and assignment before signalling stop and after observing completion. Existing lifecycle code joins compute, settles decision/sink work and observes source, sink and connector-child termination. No request to cancel or close is accepted as terminal proof.

The parent catalog/coordinator identity, cut hold and namespace lock remain owned, with the runtime in ShuttingDown. The target stays unstarted. No receipt or authority append, topology Commit, target install or Release occurs. Public start/stop remain fenced.

The total budget is 45 seconds. Cancellation or error retains unresolved DB-owned handles and the held boundary; retry with the same image, or use coordinated recovery after abort. Dropping the image never reopens intake. Its observation must be revalidated at installation.

Errors

Rejects another database’s image, stale authority, loss of the held parent, concurrent recovery/shutdown/fault, and unobserved runtime or connector termination.

impl LaminarDB

pub async fn submit_cluster_topology_change( &self, request: &ClusterTopologyRequest, ) -> Result<TopologyAdmissionStatus, DbError>

Admit an atomic topology candidate and return its durable operation receipt.

The existing recovery monitor owns all subsequent phases. Cancellation or a lost response cannot revoke admission. This response does not claim target activation; query status with the same UUID. Identical retries return the recorded operation before compiling again. A follower forwards at most once to the durable leader within the same 45 second budget.

Errors

Rejects changed payloads, stale parents, unsupported plans, missing live coordinator, unresolved authority, compiler contention and bounded deadlines. A timeout is uncertain: reread status and retry the same identity rather than allocate a replacement request.

pub async fn adopt_cluster_topology( &self, request: &ClusterTopologyAdoptionRequest, ) -> Result<LegacyTopologyBaseline, DbError>

Explicitly adopt topology one without rewriting the existing catalog or checkpoint storage.

Errors

Requires the coordinated-upgrade assertion, exact existing deployment/manifest, live leadership and the existing bounded adoption CAS. A follower forwards at most once.

impl LaminarDB

pub async fn certify_cluster_topology_target_preparation( &self, image: &mut PreparedTopologyRestore, ) -> Result<TopologyAdmissionStatus, DbError>

Certify this database’s private exact-root target after observing parent retirement. Reuses the existing terminal lifecycle even on retry, then publishes one exact-process receipt through the configured controller. The caller cannot supply a termination flag, root, process identity or receipt. The target remains unstarted and the parent cut, namespace and catalog remain held. This does not commit or activate the target.

The total cooperative deadline is 45 seconds. Unresolved runtime owners remain in the DB; the image stays owned by the caller. A cancelled/uncertain append may have succeeded: query operation status and retry this same image. Dropping an image never releases intake. The durable receipt is historical evidence, not a promise that this image is still resident.

Errors

Rejects foreign/stale images, authority/recovery faults and unobserved termination.

impl LaminarDB

pub async fn prepare_cluster_topology_transport( &self, image: &mut PreparedTopologyRestore, ) -> Result<(), DbError>

Fence this process’s transport and private graph to the exact committed target. Reobserves retirement for a held parent; a Created DB must have no runtime/connector owners. Current full-roster, process/adoption, assignment, source availability and Commit are audited around publication. Sources, sinks, local catalog/coordinator and intake remain unstarted/held.

The cooperative budget is 45 seconds. Cancellation after local publication retains the target fence and cut hold; retry this image or reconstruct from the immutable Commit. This is transport preparation, not installed receivers/state/sinks readiness or Release.

Errors

Rejects foreign/uncommitted/stale images, unresolved actors, process/assignment mismatches, local faults, damaged cursors and expired deadlines. Runtime DDL remains guarded.

impl LaminarDB

pub async fn cluster_topology_operation_status( &self, operation_id: TopologyOperationId, ) -> Result<Option<TopologyAdmissionStatus>, DbError>

Read an admitted request’s definitive status; no request ownership depends on this call.

Errors

Fails outside cluster mode or for unavailable/corrupt durable evidence.

pub async fn cluster_topology_status( &self, ) -> Result<ClusterTopologyStatus, DbError>

Read the cluster’s durable topology and this process’s local activation evidence.

This is a control-path read, with no catalog mutation, checkpoint allocation or source effects. It does not declare that other participants have activated.

Errors

Fails outside cluster mode or for unavailable, corrupt or inconsistent authority.

impl LaminarDB

pub fn open() -> Result<Arc<Self>, DbError>

Create an embedded in-memory database with default settings.

Errors

Returns DbError if DataFusion context creation fails.

pub fn open_with_config(config: LaminarConfig) -> Result<Arc<Self>, DbError>

Create with custom configuration.

Errors

Returns DbError if the configuration is invalid or DataFusion context creation fails.

pub async fn adopt_assignment_snapshot( &self, snapshot: AssignmentSnapshot, deadline: Instant, ) -> Result<SnapshotAdoption, DbError>

Adopt one authority-audited assignment, staging exact committed frames for live vnode acquisition. Startup recovery still restores the complete graph before launch.

Errors

Returns a checkpoint error when authority, state, or the deadline changes before atomic publication. The assignment is not published in that case.

pub async fn collect_local_table( &self, name: &str, ) -> Result<Vec<RecordBatch>, DbError>

Collect this node’s physical table slice without invoking distributed fan-out.

This is intended for cluster diagnostics and placement validation. It deliberately returns immutable batches rather than exposing the mutable DataFusion catalog.

Errors

Returns an error when the local table cannot be resolved, planned, or collected.

pub fn builder() -> LaminarDbBuilder

Returns a fluent builder for constructing a LaminarDB.

pub fn connector_registry(&self) -> &ConnectorRegistry

Returns the frozen connector registry for factory lookup and deployment introspection. Custom factories must be registered through LaminarDbBuilder::register_connector.

pub async fn execute(&self, sql: &str) -> Result<ExecuteResult, DbError>

Execute a SQL statement.

Errors

Returns DbError if SQL parsing, planning, or execution fails.

pub async fn execute_cluster_bootstrap( &self, sql: &str, ) -> Result<ExecuteResult, DbError>

Apply one startup catalog definition and seal it as the complete inventory. Prefer Self::execute_cluster_bootstrap_batch for server configuration.

Errors

Returns an error when the definition is invalid or the catalog batch cannot be sealed.

pub fn get_session_property(&self, key: &str) -> Option<String>

Return a session property value.

pub fn session_properties(&self) -> HashMap<String, String>

Return all session properties.

pub fn set_session_property(&self, key: &str, value: &str)

Set a session property (keys are lowercased).

pub async fn subscribe<T: FromBatch>( &self, name: &str, ) -> Result<TypedSubscription<T>, DbError>

Subscribe to a named stream or materialized view.

Rows are matched to T by column name. A changelog view’s frames carry __weight (see Self::open_subscription); a T without that field receives retracted rows as if they were inserted.

Errors

Returns DbError::StreamNotFound if the object or its output schema is unresolved.

pub fn lookup_subscription_schema(&self, name: &str) -> Option<SchemaRef>

Schema a SUBSCRIBE against name would emit. A stream is visible here only after its physical output schema has been resolved. Bare sources and unresolved streams are not subscribable.

pub async fn open_subscription( &self, name: &str, filter_sql: Option<&str>, start: SubscribeStart, ) -> Result<SubscriptionPortal, DbError>

Open a SUBSCRIBE portal against a named MV or resolved stream. A bare SOURCE is not subscribable (surfaced as StreamNotFound).

A materialized view’s portal first delivers the view’s rows, then each change to them. A changelog view’s rows carry an Int64 __weight column: +1 in the snapshot, and in a change the amount by which the change altered the row’s count (a replaced row is retracted with -1). An append view delivers plain rows; rows leaving its retention are not changes. Outside a cluster a view subscription starts at the latest cycle and admits only SubscribeStart::Tail. In a cluster it reads committed checkpoints: the view at the newest one or at SubscribeStart::AsOfEpoch, then each later checkpoint’s change, each followed by a progress frame.

Errors

StreamNotFound for unknown name; Subscription for unsupported cluster plans or durable replay failures; Pipeline for subscriber-cap or filter-compile failures; Local epoch and sequence replay failures return the corresponding structured SubscriptionEpochNotCommitted, SubscriptionReplayPruned, SubscriptionSequenceNotPublished, or SubscriptionSequencePruned error.

pub fn source<T: Record>(&self, name: &str) -> Result<SourceHandle<T>, DbError>

Get a typed handle for pushing data to a registered source.

Errors

Returns DbError::SourceNotFound if the source is not registered. Returns DbError::SchemaMismatch if the Rust type’s schema doesn’t match.

pub fn source_untyped(&self, name: &str) -> Result<UntypedSourceHandle, DbError>

Get an untyped source handle for pushing RecordBatch data.

Errors

Returns DbError::SourceNotFound if the source is not registered.

pub fn sources(&self) -> Vec<SourceInfo>

List registered sources.

pub fn sinks(&self) -> Vec<SinkInfo>

List registered sinks.

pub fn materialized_views(&self) -> Vec<MaterializedViewInfo>

List registered materialized views.

pub fn streams(&self) -> Vec<StreamInfo>

List registered streams.

pub fn pipeline_topology(&self) -> PipelineTopology

Build the pipeline topology graph (nodes + edges) from registered sources, streams, and sinks.

pub fn queries(&self) -> Vec<QueryInfo>

List active queries.

pub fn is_checkpoint_enabled(&self) -> bool

Returns whether streaming checkpointing is enabled.

pub async fn checkpoint(&self) -> Result<CheckpointResult, DbError>

Trigger a checkpoint that persists source offsets, sink positions, and operator state.

Errors

Returns DbError::Checkpoint if checkpointing is disabled, no live manual-checkpoint route exists, cluster leadership cannot be resolved, or the checkpoint fails.

pub async fn checkpoint_with_timeout( &self, timeout: Duration, ) -> Result<CheckpointResult, DbError>

Trigger one manual checkpoint within a caller-provided relative budget.

The budget is capped by the configured checkpoint timeout. It bounds admission and attempt work; once an exact attempt is reserved, this call waits for terminal cleanup even if that requires the coordinator’s private cleanup budget.

Errors

Returns DbError::Checkpoint under the same conditions as Self::checkpoint, or when the caller-provided budget cannot be represented as an absolute deadline.

pub async fn checkpoint_stats(&self) -> Option<CheckpointStats>

Returns checkpoint performance statistics, or None if the coordinator is not initialized.

impl LaminarDB

pub fn uptime(&self) -> Duration

Time elapsed since the database was created.

pub fn set_engine_metrics(&self, metrics: Arc<EngineMetrics>)

Inject prometheus engine metrics. Called once at startup before start().

The metrics report this database’s per-node memory budgets. A cluster database also reports the shuffle endpoints its builder installed.

pub fn set_prometheus_registry( &self, registry: Arc<Registry>, ) -> Result<(), DbError>

Inject a shared Prometheus registry for connector-level metrics.

Called once at startup, after the registry is constructed but before start(). Connectors created after this call will register their metrics on this registry so they appear in the scrape output.

Errors

Returns an error after the database leaves Created or when a registry was already installed.

pub fn engine_metrics(&self) -> Option<Arc<EngineMetrics>>

Get the engine metrics if set.

pub fn cluster_subscription_output_health( &self, ) -> Option<ClusterSubscriptionOutputHealth>

Read process-local committed subscription output-log health without storage I/O.

pub fn checkpoint_barrier_timing_snapshot( &self, expected_process: Option<LocalProcessAuthorityIdentity>, after_sequence: u64, limit: usize, ) -> Result<CheckpointBarrierTimingPage, CheckpointBarrierTimingReadError>

Read one bounded, process-bound page of local cluster checkpoint barrier timings.

This is an in-memory diagnostic read. It performs no checkpoint, state-backend, network, filesystem, or object-store operation. A continuation cursor is the pair of expected_process and after_sequence; callers must retain both from the prior page. Snapshot counters may advance immediately after this call, so certification must finish with a quiescent repeated read rather than treating one page as a stable cut.

Errors

Returns an error when a continuation omits or mismatches its process identity, live process authority cannot be sampled without waiting, authority changes during the read, or the bounded ledger snapshot rejects its cursor/page request.

pub fn pipeline_state(&self) -> &'static str

Get the current pipeline state as a string.

pub fn last_fault(&self) -> Option<String>

The last runtime-fault or terminal resource-exhaustion reason. Populated when state is Faulted; cleared on a clean start.

pub fn metrics(&self) -> PipelineMetrics

Get a pipeline-wide metrics snapshot.

Reads prometheus engine metrics and catalog sizes to produce a point-in-time view of pipeline health.

pub fn source_metrics(&self, name: &str) -> Option<SourceMetrics>

Get metrics for a single source by name.

pub fn all_source_metrics(&self) -> Vec<SourceMetrics>

Get metrics for all registered sources.

pub fn stream_metrics(&self, name: &str) -> Option<StreamMetrics>

Get metrics for a single stream by name.

pub fn all_stream_metrics(&self) -> Vec<StreamMetrics>

Get metrics for all registered streams.

pub fn total_events_processed(&self) -> u64

Get the total number of events processed (ingested + emitted).

pub fn pipeline_watermark(&self) -> i64

Returns the global pipeline watermark (minimum across all source watermarks).

Returns i64::MIN if no watermark-enabled sources exist or no events have been processed.

pub fn cancel_query(&self, query_id: u64) -> Result<(), DbError>

Cancel a running query by ID.

Marks the query as inactive in the catalog. Future subscription polls for this query will receive no more data.

Errors

Returns DbError if the query is not found.

pub fn source_count(&self) -> usize

Get the number of registered sources.

pub fn sink_count(&self) -> usize

Get the number of registered sinks.

pub fn checkpoint_stats_nonblocking(&self) -> Option<CheckpointStats>

Returns checkpoint statistics if available (non-blocking).

Uses try_lock() on the coordinator mutex. Returns None if the coordinator is not initialized or the lock is contended.

pub fn active_query_count(&self) -> usize

Get the number of active queries.

impl LaminarDB

pub fn is_closed(&self) -> bool

Returns true if the database has been shut down.

pub fn close(&self)

Fence new work and wake the runtime so it can shut down.

pub fn enable_supervision(self: &Arc<Self>)

Enable auto-restart from the last checkpoint on a fault. Without it, a fault parks in Faulted for manual restart (the embedded default).

pub fn fence_cluster_startup(&self)

Keep clustered source intake closed while startup restores state and certifies assignment. Call before Self::start; Self::finish_cluster_startup is the only startup path that opens the gate.

pub fn revoke_cluster_authority(&self)

Permanently withdraw this process’s clustered data-plane authority after lease loss.

pub fn cluster_intake_fenced(&self) -> bool

Whether clustered source and shuffle intake is still fenced.

pub fn coordinated_recovery_in_progress(&self) -> bool

Whether a clustered runtime is held by coordinated recovery lifecycle authority.

impl LaminarDB

pub async fn finish_cluster_startup( &self, deadline: Instant, ) -> Result<ClusterStartupDisposition, DbError>

Finish clustered startup after the exact assignment fence is available.

Fresh nodes open intake only when no durable recovery round exists. A process that restored local state, or one that observes an active/stale round, remains fenced and requests a full coordinated rewind.

Errors

Returns a checkpoint error when the local assignment has not been certified. Intake remains closed when recovery authority is unavailable so the monitor can retry without admitting records.

pub async fn prepare_cluster_startup_recovery_generation( &self, deadline: Instant, ) -> Result<(), DbError>

Import the last recovery generation that reached an irrevocable cluster Release before a fresh pipeline starts. The allocation high-watermark is deliberately not used: a driver can reserve a generation and fail before any data plane rewinds to it.

Errors

Returns an error when durable recovery authority is unavailable, the process lease is lost, or an already-active transport conflicts with the committed terminal.

pub fn enable_coordinated_recovery(self: &Arc<Self>) -> Result<(), DbError>

Start the database-owned per-node recovery supervisor once. Coordinated recovery is the only cluster fault path — a local-only restart rewinds one node while peers advance, an inconsistent cut.

Errors

Returns an error if the database-owned control runtime cannot be initialized.

impl LaminarDB

pub async fn shutdown(&self) -> Result<(), DbError>

Shut down the streaming pipeline gracefully. Idempotent.

Errors

Returns Err if the watcher task panicked.

pub async fn stop_pipeline(&self) -> Result<(), DbError>

Stop the streaming pipeline so it can be restarted.

Errors

Returns DbError::InvalidOperation if the pipeline is still starting or the coordinator does not exit within the stop timeout.

impl LaminarDB

pub async fn start(self: &Arc<Self>) -> Result<(), DbError>

Start the streaming pipeline. Idempotent if already running. On failure (or recovering from Faulted) it rebuilds from the surviving catalog.

The first start logs a warning when the per-node memory budgets add up to more than the process’s cgroup memory limit.

Errors

Returns an error if the pipeline cannot be started.

impl LaminarDB

pub async fn prepare_committed_cluster_topology_startup( &self, ) -> Result<bool, DbError>

Prepare a cold committed target for the existing coordinated recovery supervisor. Returns true when that supervisor must restore and release the actual target actors; false means there is no live topology Commit and ordinary startup remains applicable: a settled target restores its own committed checkpoint like any other deployment. No actors, sink epochs or intake are started here. The DB remains Created and fenced.

Errors

Rejects live/closed/terminal instances, missing deployment identity, divergent target inventory/environment, absent checkpoint storage or stale process/catalog authority.

impl LaminarDB

pub fn process_function_bootstrap_sql( &self, output_name: &str, ) -> Result<String, DbError>

Return the canonical invocation DDL for a registered cluster process binding. Include this statement after its source and before its consumers in Self::execute_cluster_bootstrap_batch. Every owner must register the same immutable implementation before bootstrapping or replaying that catalog. SQL never loads code.

Errors

Rejects an unknown binding or an incompatible manifest.

impl LaminarDB

pub fn process_functions(&self) -> Vec<ProcessFunctionInfo>

Inspect process functions registered on this database instance.

pub async fn register_native_process_function( &self, output_name: &str, source_name: &str, descriptor: ProcessFunctionDescriptor, handler: Arc<dyn NativeProcessFunction>, ) -> Result<(), DbError>

Register a trusted native keyed process function over one append-only source. Registration is offline: call it after creating a local source and before start(). The caller must register the same immutable implementation when constructing a replacement database instance that restores an existing checkpoint.

Local at-least-once execution requires checkpointing and a replayable append-only connector that reproduces one channel in fixed replay batches with deterministic positions. Only one logical source is admitted. Source and sink contracts are verified before startup I/O. A direct in-memory source is available only with best-effort delivery. Cluster execution admits at-least-once delivery with a splittable fixed-batch source. Register the binding on every owner before catalog bootstrap, then include process_function_bootstrap_sql() after the source in the ordered startup batch. Process bindings cannot be changed through live catalog mutations. Native code runs in the compute process and must be trusted and nonblocking.

Errors

Rejects incompatible schemas, identities, source modes, runtime modes, or resource limits.

pub async fn register_remote_process_function( &self, output_name: &str, source_name: &str, descriptor: ProcessFunctionDescriptor, client: Arc<RemoteProcessClient>, ) -> Result<(), DbError>

Register a connected loopback Rust or Python worker. At-least-once Python requires a replay-safe descriptor and the live binding supplied by LocalPythonWorker on Linux. Its complete package must belong to the read-only root image; a standalone connected client does not supply that binding. Undeclared Python supports best-effort delivery. Source-order and cluster-bootstrap requirements match native registration. The caller owns the worker process lifecycle and must keep it available until shutdown.

Errors

Rejects mismatched descriptors, unsupported modes, schemas, or resource limits.

impl LaminarDB

pub async fn build_show_checkpoint_status(&self) -> Result<RecordBatch, DbError>

Build a SHOW CHECKPOINT STATUS metadata result. Public so the server’s GET /api/v1/cluster/checkpoints endpoint can surface it.

Errors

Returns DbError::Checkpoint if the metadata batch cannot be assembled.

impl LaminarDB

pub async fn cluster_vnode_load(&self) -> Result<VnodeLoadReport, DbError>

How keyed operator state spreads over vnodes: this node’s live state at the graph’s last metrics sample, and every participant’s frame sizes at the newest committed checkpoint this node knows. Live state needs Self::set_engine_metrics; frame sizes need checkpointing.

Errors

Fails when the committed checkpoint’s manifests cannot be read within 10 seconds.

Trait Implementations

impl Debug for LaminarDB

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for LaminarDB

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.