Struct Session 

pub struct Session { /* private fields */ }

A database session — the primary scope for reads.

All data access goes through sessions. Sessions hold scoped query parameters and a private copy of the Locy rule registry. They are the factory for Transactions (write scope).

Sessions are cheap to create (sync, no I/O) and cheap to clone (Arc-based).

Examples

let mut session = db.session();
session.set("tenant", 42);

let rows = session.query("MATCH (n) WHERE n.tenant = $tenant RETURN n").await?;

// Transactions for writes
let tx = session.tx().await?;
tx.execute("CREATE (:Person {name: 'Alice'})").await?;
tx.commit().await?;

Implementations

impl Session

pub fn params(&self) -> Params<'_>

Access the session-scoped parameter store.

pub async fn query(&self, cypher: &str) -> Result<QueryResult>

Execute a read-only Cypher query.

Uses the transparent plan cache: repeated queries with the same text skip parsing and planning. Cache entries auto-invalidate on schema changes.

pub fn query_with(&self, cypher: &str) -> QueryBuilder<'_>

Execute a read-only Cypher query with a builder for parameters.

pub async fn locy(&self, program: &str) -> Result<LocyResult>

Evaluate a Locy program with default configuration.

pub fn locy_with(&self, program: &str) -> LocyBuilder<'_>

Evaluate a Locy program with parameters using a builder.

pub fn rules(&self) -> RuleRegistry<'_>

Access the session-scoped rule registry.

pub fn compile_locy(&self, program: &str) -> Result<CompiledProgram>

Compile a Locy program without executing it, using this session’s rule registry.

pub async fn tx(&self) -> Result<Transaction>

Create a new transaction for multi-statement writes.

Only one write context (transaction or bulk writer) can be active per session at a time. Returns ReadOnly if the session is pinned.

pub fn tx_with(&self) -> TransactionBuilder<'_>

Create a transaction with builder options (timeout, isolation level).

pub async fn pin_to_version(&mut self, snapshot_id: &str) -> Result<()>

Pin this session to a specific snapshot version.

All subsequent reads see data as of that version. Writes are rejected.

pub async fn pin_to_timestamp(&mut self, ts: DateTime<Utc>) -> Result<()>

Pin this session to a specific timestamp.

Resolves the closest snapshot at or before the given timestamp, then pins the session to that snapshot. Writes are rejected while pinned.

pub async fn refresh(&mut self) -> Result<()>

Refresh: unpin the session, returning to the live database state.

In single-process mode, this simply unpins the session. In multi-agent mode (Phase 2), this picks up the latest committed version from storage.

pub fn is_pinned(&self) -> bool

Returns true if the session is pinned to a specific version.

pub fn cancel(&self)

Cancel all in-flight queries in this session.

Queries check is_cancelled() at each operator boundary via check_timeout(). After cancellation, a fresh token is created so the session remains usable.

pub fn cancellation_token(&self) -> CancellationToken

Get a clone of this session’s cancellation token.

Useful for external cancellation (e.g. from a timeout task).

pub async fn prepare(&self, cypher: &str) -> Result<PreparedQuery>

Prepare a Cypher query for repeated execution.

The query is parsed and planned once; subsequent executions skip those phases. If the schema changes, the prepared query auto-replans.

pub async fn prepare_locy(&self, program: &str) -> Result<PreparedLocy>

Prepare a Locy program for repeated evaluation.

pub fn add_hook( &mut self, name: impl Into<String>, hook: impl SessionHook + 'static, )

Add a named session hook for query/commit interception.

pub fn remove_hook(&mut self, name: &str) -> bool

Remove a hook by name. Returns true if it existed.

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

List names of all registered hooks.

pub fn clear_hooks(&mut self)

Remove all hooks.

pub fn watch(&self) -> CommitStream

Watch for all commit notifications.

pub fn watch_with(&self) -> WatchBuilder

Watch for commit notifications with filters.

pub fn id(&self) -> &str

Get the session ID.

pub fn capabilities(&self) -> SessionCapabilities

Query the capabilities of this session.

Returns a snapshot of what the session can do in its current mode.

pub fn metrics(&self) -> SessionMetrics

Snapshot the session’s accumulated metrics.

Trait Implementations

impl Clone for Session

fn clone(&self) -> Self

Clone the session, sharing the plan cache with the original.

The cloned session gets a fresh ID, fresh metrics counters, and a fresh cancellation token, but shares the plan cache so cache hits benefit all clones. The database’s active session count is incremented.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Session

fn drop(&mut self)

Executes the destructor for this type.