Struct Database 

pub struct Database<S> { /* private fields */ }

Owns the graph store and orchestrates parse → analyze → compile → execute.

Optionally drives a write-ahead log: when constructed via Database::open_with_wal or Database::recover the database holds an Arc<WalRecorder> that brackets every query with begin → mutations → commit/abort → flush while the store write lock is held, so the WAL order is exactly the in-memory commit order. When constructed via Database::in_memory / Database::from_graph the WAL handle is None and the engine pays only the existing MutationRecorder::record null-pointer check per mutation.

Implementations

impl Database<InMemoryGraph>

pub fn in_memory() -> Self

Convenience constructor: a fresh, empty in-memory graph database.

pub fn open_with_wal(wal_config: WalConfig) -> Result<Self, LoraError>

Open or create a WAL-enabled in-memory database from a fresh graph.

WalConfig::Disabled falls back to Database::in_memory. Otherwise, opens the WAL directory, replays any committed events into a fresh graph, installs a WalRecorder on the graph, and returns a database ready to serve queries.

To restore from a snapshot in addition to the WAL, use Database::recover instead.

pub fn open_with_wal_snapshots( wal_config: WalConfig, snapshot_config: SnapshotConfig, ) -> Result<Self, LoraError>

Open or create a WAL-backed database with managed snapshots beside it.

Recovery loads the newest managed snapshot first, then replays WAL records above the snapshot’s LSN fence. Checkpoints are written through Self::checkpoint_managed / Self::sync, or automatically when snapshot_config.checkpoint_every_commits is set.

pub fn open_named( database_name: impl AsRef<str>, options: DatabaseOpenOptions, ) -> Result<Self, LoraError>

Open or create a named portable database rooted under options.database_dir.

The database name may be either a portable basename (app or app.loradb) or a safe relative path (tenant/app). It is resolved under options.database_dir before the WAL archive backend opens.

pub fn recover( snapshot_path: impl AsRef<Path>, wal_config: WalConfig, ) -> Result<Self, LoraError>

Restore from a snapshot file then replay any WAL records past it.

The snapshot’s wal_lsn (when set) becomes the replay fence — events at or below that LSN are already represented in the loaded snapshot and are skipped. A missing snapshot file is treated as “fresh start” so operators can pass the same path on every boot.

If the WAL contains a checkpoint marker newer than the snapshot’s wal_lsn, a one-line warning is printed to stderr — the snapshot is stale relative to a more recent checkpoint the operator is presumably aware of. Recovery still proceeds from the snapshot’s fence (replay re-applies every record above it, which is conservative-correct); a tighter contract is deferred to v2 because verifying that the marker’s snapshot file actually exists and is loadable is a separate observability concern.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn from_graph(graph: S) -> Self

Build a database by taking ownership of a bare graph store.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn execute( &self, query: &str, options: Option<ExecuteOptions>, ) -> Result<QueryResult, LoraError>

Execute a query and return its result.

pub fn execute_with_timeout( &self, query: &str, options: Option<ExecuteOptions>, timeout: Duration, ) -> Result<QueryResult, LoraError>

Execute a query with a cooperative deadline. The timeout is checked at executor operator boundaries and hot scan loops; if it fires, the query returns an error and any WAL-backed mutating query is aborted through the existing failure path.

pub fn execute_with_params( &self, query: &str, options: Option<ExecuteOptions>, params: BTreeMap<String, LoraValue>, ) -> Result<QueryResult, LoraError>

Execute a query with bound parameters.

When a WAL is attached the call is bracketed by a transaction:

1. recorder.arm() after analyze + compile (so a parse / semantic / compile error never opens a tx that has to be immediately aborted). Arming is cheap: no record is appended to the WAL yet, so a pure read query that completes here pays nothing for the WAL hot path.
2. The executor runs; every primitive mutation fires MutationRecorder::record, which buffers events in memory.
3. On Ok, recorder.commit() writes TxBegin, one batched mutation record, and TxCommit only when mutations occurred, then applies the WAL’s configured single-thread flush policy.
4. On Err, recorder.abort() clears the pending batch. The engine has no rollback, so the in-memory state may already be partially mutated; the live handle is quarantined while durable recovery stays atomic because no committed batch was written.
5. The recorder’s poisoned flag is polled once. If set, the query fails loudly with the durability error so the caller can act on it; the WAL refuses further appends until the operator restarts the database, which recovers from the last consistent snapshot + WAL.

pub fn execute_with_params_timeout( &self, query: &str, options: Option<ExecuteOptions>, params: BTreeMap<String, LoraValue>, timeout: Duration, ) -> Result<QueryResult, LoraError>

Execute a parameterised query with a cooperative deadline.

pub fn execute_rows(&self, query: &str) -> Result<Vec<Row>, LoraError>

Execute a query and return hydrated rows before final result-format projection.

pub fn execute_rows_with_params( &self, query: &str, params: BTreeMap<String, LoraValue>, ) -> Result<Vec<Row>, LoraError>

Execute a query with parameters and return hydrated rows before final result-format projection.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn explain( &self, query: &str, _params: Option<BTreeMap<String, LoraValue>>, ) -> Result<QueryPlan, LoraError>

Compile query and return the plan that would run.

The executor is not invoked: explain is a pure planning call and never produces side effects. Mutating queries return their plan without touching the graph.

params is accepted for symmetry with execute(). The returned plan is identical regardless of the parameter values today; future cost-model work may use parameter values for selectivity estimation, so callers should pass real values when they have them.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn graph_contains_node(&self, id: NodeId) -> bool

pub fn graph_node(&self, id: NodeId) -> Option<NodeRecord>

pub fn graph_all_node_ids(&self) -> Vec<NodeId>

pub fn graph_node_ids_by_label(&self, label: &str) -> Vec<NodeId>

pub fn graph_all_nodes(&self) -> Vec<NodeRecord>

pub fn graph_nodes_by_label(&self, label: &str) -> Vec<NodeRecord>

pub fn graph_node_has_label(&self, id: NodeId, label: &str) -> bool

pub fn graph_node_labels(&self, id: NodeId) -> Option<Vec<String>>

pub fn graph_node_properties( &self, id: NodeId, ) -> Option<BTreeMap<String, LoraValue>>

pub fn graph_node_property(&self, id: NodeId, key: &str) -> Option<LoraValue>

pub fn graph_contains_relationship(&self, id: RelationshipId) -> bool

pub fn graph_relationship( &self, id: RelationshipId, ) -> Option<RelationshipRecord>

pub fn graph_all_relationship_ids(&self) -> Vec<RelationshipId>

pub fn graph_relationship_ids_by_type( &self, rel_type: &str, ) -> Vec<RelationshipId>

pub fn graph_all_relationships(&self) -> Vec<RelationshipRecord>

pub fn graph_relationships_by_type( &self, rel_type: &str, ) -> Vec<RelationshipRecord>

pub fn graph_relationship_endpoints( &self, id: RelationshipId, ) -> Option<(NodeId, NodeId)>

pub fn graph_relationship_type(&self, id: RelationshipId) -> Option<String>

pub fn graph_relationship_properties( &self, id: RelationshipId, ) -> Option<BTreeMap<String, LoraValue>>

pub fn graph_relationship_property( &self, id: RelationshipId, key: &str, ) -> Option<LoraValue>

pub fn graph_relationship_ids_of( &self, node_id: NodeId, direction: GraphDirection, ) -> Vec<RelationshipId>

pub fn graph_degree(&self, node_id: NodeId, direction: GraphDirection) -> usize

pub fn graph_neighbors( &self, node_id: NodeId, direction: GraphDirection, types: &[String], ) -> Vec<NodeRecord>

pub fn graph_expand_ids( &self, node_id: NodeId, direction: GraphDirection, types: &[String], ) -> Vec<(RelationshipId, NodeId)>

pub fn graph_all_labels(&self) -> Vec<String>

pub fn graph_all_relationship_types(&self) -> Vec<String>

pub fn graph_all_property_keys(&self) -> Vec<String>

pub fn graph_all_node_property_keys(&self) -> Vec<String>

pub fn graph_all_relationship_property_keys(&self) -> Vec<String>

pub fn graph_label_property_keys(&self, label: &str) -> Vec<String>

pub fn graph_relationship_type_property_keys( &self, rel_type: &str, ) -> Vec<String>

pub fn graph_find_node_ids_by_property( &self, label: Option<&str>, key: &str, value: LoraValue, ) -> Result<Vec<NodeId>>

pub fn graph_find_relationship_ids_by_property( &self, rel_type: Option<&str>, key: &str, value: LoraValue, ) -> Result<Vec<RelationshipId>>

pub fn graph_create_node( &self, labels: Vec<String>, properties: BTreeMap<String, LoraValue>, ) -> Result<NodeRecord, LoraError>

pub fn graph_create_relationship( &self, src: NodeId, dst: NodeId, rel_type: &str, properties: BTreeMap<String, LoraValue>, ) -> Result<Option<RelationshipRecord>, LoraError>

pub fn graph_set_node_property( &self, node_id: NodeId, key: String, value: LoraValue, ) -> Result<bool, LoraError>

pub fn graph_remove_node_property( &self, node_id: NodeId, key: &str, ) -> Result<bool, LoraError>

pub fn graph_add_node_label( &self, node_id: NodeId, label: &str, ) -> Result<bool, LoraError>

pub fn graph_remove_node_label( &self, node_id: NodeId, label: &str, ) -> Result<bool, LoraError>

pub fn graph_set_node_labels( &self, node_id: NodeId, labels: Vec<String>, ) -> Result<bool, LoraError>

pub fn graph_replace_node_properties( &self, node_id: NodeId, properties: BTreeMap<String, LoraValue>, ) -> Result<bool, LoraError>

pub fn graph_merge_node_properties( &self, node_id: NodeId, properties: BTreeMap<String, LoraValue>, ) -> Result<bool, LoraError>

pub fn graph_set_relationship_property( &self, rel_id: RelationshipId, key: String, value: LoraValue, ) -> Result<bool, LoraError>

pub fn graph_remove_relationship_property( &self, rel_id: RelationshipId, key: &str, ) -> Result<bool, LoraError>

pub fn graph_replace_relationship_properties( &self, rel_id: RelationshipId, properties: BTreeMap<String, LoraValue>, ) -> Result<bool, LoraError>

pub fn graph_merge_relationship_properties( &self, rel_id: RelationshipId, properties: BTreeMap<String, LoraValue>, ) -> Result<bool, LoraError>

pub fn graph_delete_relationship( &self, rel_id: RelationshipId, ) -> Result<bool, LoraError>

pub fn graph_delete_node(&self, node_id: NodeId) -> Result<bool, LoraError>

pub fn graph_detach_delete_node( &self, node_id: NodeId, ) -> Result<bool, LoraError>

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn profile( &self, query: &str, params: Option<BTreeMap<String, LoraValue>>, ) -> Result<QueryProfile, LoraError>

Execute query and return the plan plus runtime metrics.

PROFILE executes the query for real. Mutating queries (CREATE / MERGE / SET / DELETE / REMOVE) produce exactly the same side effects as execute() — the WAL is written, snapshots observe the commit, and the live store advances. Use Database::explain to inspect a plan without running it.

impl Database<InMemoryGraph>

pub fn begin_transaction( &self, mode: TransactionMode, ) -> Result<Transaction<'_>, LoraError>

Start an explicit transaction.

Read-only transactions hold a shared read lock for their lifetime; read-write transactions hold the write lock. The staging clone is lazy — it only happens when a TransactionMode::ReadWrite transaction sees its first mutating statement. Materialized read-only statements run straight against the live graph; tx-bound streams may still clone so their cursors can own a stable view. ReadWrite transactions that perform only materialized reads (or commit empty) pay nothing for staging.

pub fn stream(&self, query: &str) -> Result<QueryStream<'_>, LoraError>

Execute a query and return an owning row stream.

pub fn stream_with_params( &self, query: &str, params: BTreeMap<String, LoraValue>, ) -> Result<QueryStream<'_>, LoraError>

Execute a parameterised query and return an owning row stream.

The compiled plan is classified at open time. Read-only queries run directly off the live store and yield a buffered cursor with plan-derived columns. Mutating queries are routed through a hidden read-write Transaction: full cursor exhaustion calls tx.commit (publishing staged changes and replaying the tx-local WAL buffer); a premature drop or any error from next_row calls tx.rollback so the live store and the WAL stay untouched.

pub unsafe fn stream_with_params_owned( self: &Arc<Self>, query: &str, params: BTreeMap<String, LoraValue>, ) -> Result<QueryStream<'static>, LoraError>

Open a stream whose lifetime can be carried by an outer owner that also retains an Arc<Database>.

Safety

The returned stream may contain lock guards that borrow from the database’s internal RwLock. The caller must keep this exact Arc alive until the stream is dropped. This is intended for language bindings that store both the Arc<Database> and the QueryStream in the same opaque stream handle.

impl Database<InMemoryGraph>

pub fn sync(&self) -> Result<(), LoraError>

Force any pending WAL bytes to durable storage and, for container-backed named databases, refresh the portable .loradb file before returning.

Managed snapshot checkpoints are explicit via Self::checkpoint_managed or threshold-driven via [SnapshotConfig::checkpoint_every_commits]; sync() remains a durability operation rather than an O(graph) checkpoint.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn wal(&self) -> Option<&Arc<WalRecorder>>

Handle to the installed WAL recorder, if any. Exposed for admin paths (checkpoint, truncate, observability) that need to drive the WAL outside the standard query lifecycle.

pub fn snapshot(&self) -> Arc<S>

Snapshot the current authoritative graph. Equivalent to the historical database.store().load_full() pattern, exposed here so external callers don’t need to name the internal storage wrapper.

pub fn parse(&self, query: &str) -> Result<Document, LoraError>

Parse a query string into an AST without executing it.

impl<S> Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

pub fn try_clear(&self) -> Result<(), LoraError>

Drop every node and relationship, returning WAL/archive errors to the caller.

When a WAL is attached, the buffered MutationEvent::Clear is appended to the log on success. The clear runs in place against the live graph via the same fast path as with_logged_store_mut, so a large graph clear no longer pays an O(N+E) snapshot clone.

pub fn clear(&self)

Drop every node and relationship.

This compatibility helper keeps the historical infallible Rust API. Bindings that can report errors should call Self::try_clear.

pub fn node_count(&self) -> usize

Number of nodes currently in the graph.

pub fn relationship_count(&self) -> usize

Number of relationships currently in the graph.

pub fn with_store<R>(&self, f: impl FnOnce(&S) -> R) -> R

Run a closure with a shared borrow of the underlying store. Lock-free: callers see a consistent snapshot for the duration of the closure even while writers commit new versions.

pub fn with_store_mut<R>(&self, f: impl FnOnce(&mut S) -> R) -> R

Run a closure with an exclusive borrow of the underlying store. Reserved for admin paths (restore, bulk load); regular mutation goes through execute_with_params. The closure mutates the live graph in place via Arc::make_mut, so callers don’t pay an O(N+E) snapshot clone just to overwrite the graph. Concurrent readers, when present, force a single CoW clone and keep observing their pre-mutation snapshot via the Arc<S> they already hold.

impl Database<InMemoryGraph>

pub fn save_snapshot_to( &self, path: impl AsRef<Path>, ) -> Result<SnapshotMeta, LoraError>

Serialize the current graph state to path using the default columnar codec options (uncompressed, unencrypted). Writes are atomic via <path>.tmp + rename + parent-dir fsync.

Callers that need compression or encryption should reach for Self::save_snapshot_to_with_options directly.

pub fn load_snapshot_from( &self, path: impl AsRef<Path>, ) -> Result<SnapshotMeta, LoraError>

Replace the current graph state with a snapshot loaded from path. Decodes via the columnar codec; encrypted snapshots require Self::load_snapshot_from_with_credentials instead.

pub fn in_memory_from_snapshot( path: impl AsRef<Path>, ) -> Result<Self, LoraError>

Convenience constructor: open (or create) an empty in-memory database and immediately restore it from path. Errors if the file cannot be opened or the snapshot is malformed.

pub fn save_snapshot_to_bytes(&self) -> Result<Vec<u8>, LoraError>

Serialize the current graph state into the database snapshot byte format.

This uses the column-oriented lora-snapshot codec — the same one driven by save_snapshot_to_with_options, but without a WAL fence. The default is uncompressed so bytes stay portable across native and WASM builds; callers that want a specific codec can use Self::save_snapshot_to_bytes_with_options.

pub fn save_snapshot_to_bytes_with_options( &self, options: &SnapshotOptions, ) -> Result<(Vec<u8>, SnapshotInfo), LoraError>

Serialize the current graph state into database snapshot bytes with explicit codec options.

pub fn save_snapshot_to_with_options( &self, path: impl AsRef<Path>, options: &SnapshotOptions, ) -> Result<SnapshotMeta, LoraError>

Serialize the current graph state to a database snapshot file with explicit codec options. This is the path form of Self::save_snapshot_to_bytes_with_options and supports the same compression and encryption options.

pub fn load_snapshot_from_bytes( &self, bytes: &[u8], ) -> Result<SnapshotMeta, LoraError>

Replace the current graph state from snapshot bytes (columnar lora-snapshot format).

pub fn load_snapshot_from_bytes_with_credentials( &self, bytes: &[u8], credentials: Option<&SnapshotCredentials>, ) -> Result<SnapshotMeta, LoraError>

Replace the current graph state from snapshot bytes, supplying credentials when loading an encrypted database snapshot.

pub fn load_snapshot_from_with_credentials( &self, path: impl AsRef<Path>, credentials: Option<&SnapshotCredentials>, ) -> Result<SnapshotMeta, LoraError>

Replace the current graph state from a database snapshot file, supplying credentials when the snapshot is encrypted.

pub fn checkpoint_to( &self, path: impl AsRef<Path>, ) -> Result<SnapshotMeta, LoraError>

Take a checkpoint: snapshot the current state with the WAL’s durable_lsn stamped into the header, append a Checkpoint marker to the WAL, then drop sealed segments at or below the fence.

Errors with “checkpoint requires WAL enabled” when called on a database constructed without a WAL — operators that just want a fence-less dump should use Self::save_snapshot_to instead.

The write-lock-held window covers snapshot serialization plus the checkpoint marker append. Truncation runs after the rename but still under the write lock; making it concurrent with queries is a v2 concern (see docs/decisions/0004-wal.md).

pub fn checkpoint_managed(&self) -> Result<SnapshotMeta, LoraError>

Take a checkpoint into the managed snapshot directory configured by Self::open_with_wal_snapshots.

Trait Implementations

impl<S> QueryRunner for Database<S>

where S: GraphStorage + GraphStorageMut + Any + Clone + Send + Sync + 'static,

fn execute( &self, query: &str, options: Option<ExecuteOptions>, ) -> Result<QueryResult, LoraError>

fn explain( &self, query: &str, params: Option<BTreeMap<String, LoraValue>>, ) -> Result<QueryPlan, LoraError>

Compile a query and return its plan without executing it.

fn profile( &self, query: &str, params: Option<BTreeMap<String, LoraValue>>, ) -> Result<QueryProfile, LoraError>

Execute a query and return its plan plus runtime metrics. Mutating queries are persisted exactly as in execute.

impl SnapshotAdmin for Database<InMemoryGraph>

fn save_snapshot(&self, path: &Path) -> Result<SnapshotMeta, LoraError>

fn load_snapshot(&self, path: &Path) -> Result<SnapshotMeta, LoraError>

impl WalAdmin for Database<InMemoryGraph>

fn checkpoint(&self, path: &Path) -> Result<SnapshotMeta, LoraError>

Take a checkpoint at path. The snapshot’s header is stamped with the WAL’s durable_lsn; older sealed segments are then dropped.

fn wal_status(&self) -> Result<WalStatus, LoraError>

Snapshot of the WAL’s current state — durable / next LSN, active / oldest segment id. Cheap; a single WAL mutex acquisition.

fn wal_truncate(&self, fence_lsn: u64) -> Result<(), LoraError>

Drop sealed segments at or below fence_lsn. Idempotent.