Struct Session 

pub struct Session<'a> { /* private fields */ }

Session for executing prepared statements

A session holds a reference to the database and a cache of prepared statements. Use this for executing repeated queries with different parameters.

Implementations

impl<'a> Session<'a>

pub fn new(db: &'a Database) -> Self

Create a new session with a reference to the database

Uses a default cache size of 1000 prepared statements.

pub fn with_cache_size(db: &'a Database, cache_size: usize) -> Self

Create a new session with a custom cache size

pub fn with_shared_cache( db: &'a Database, cache: Arc<PreparedStatementCache>, ) -> Self

Create a new session with a shared cache

This allows multiple sessions to share the same prepared statement cache, which is useful for connection pooling scenarios.

pub fn database(&self) -> &Database

Get the underlying database reference

pub fn cache(&self) -> &PreparedStatementCache

Get the prepared statement cache

pub fn shared_cache(&self) -> Arc<PreparedStatementCache>

Get the shared cache Arc (for sharing with other sessions)

pub fn prepare(&self, sql: &str) -> Result<Arc<PreparedStatement>, SessionError>

Prepare a SQL statement for execution

Parses the SQL and caches the result. Subsequent calls with the same SQL string will return the cached statement without re-parsing.

Supports ? placeholders for parameter binding.

Example

let stmt = session.prepare("SELECT * FROM users WHERE id = ?")?;
assert_eq!(stmt.param_count(), 1);

pub fn prepare_arena( &self, sql: &str, ) -> Result<Arc<ArenaPreparedStatement>, ArenaParseError>

Prepare a SQL SELECT statement using arena allocation

This is optimized for SELECT statements and provides better cache locality. Arena-based statements store the parsed AST in contiguous memory, which can improve performance for frequently executed queries.

For non-SELECT statements, this will return an error - use prepare() instead.

Performance Benefits

Arena allocation provides:

• Better cache locality (contiguous memory layout)
• Lower allocation overhead (single arena vs multiple heap allocations)
• Potential for zero-copy parameter binding in future phases

Example

let stmt = session.prepare_arena("SELECT * FROM users WHERE id = ?")?;
assert_eq!(stmt.param_count(), 1);

pub fn execute_prepared( &self, stmt: &PreparedStatement, params: &[SqlValue], ) -> Result<PreparedExecutionResult, SessionError>

Execute a prepared SELECT statement with parameters

Binds the parameters to the prepared statement and executes it. This is the fast path for repeated queries - no SQL parsing occurs.

For simple PK point lookups, uses cached execution plan to bypass the full query execution pipeline.

Example

let stmt = session.prepare("SELECT * FROM users WHERE id = ?")?;
let result = session.execute_prepared(&stmt, &[SqlValue::Integer(42)])?;