Struct Statement 

pub struct Statement<'c> { /* private fields */ }

A prepared statement bound to a specific connection lifetime.

SQLR-23 — Statement carries the parsed AST (parsed exactly once at prepare time), not just the raw SQL. query / run execute against the cached AST; query_with_params / execute_with_params clone the AST and substitute ? placeholders before dispatch.

Implementations

impl<'c> Statement<'c>

pub fn parameter_count(&self) -> usize

Number of ? placeholders detected in the source SQL. Strict arity validation: passing a slice of a different length to query_with_params / execute_with_params returns a typed error.

pub fn run(&mut self) -> Result<String>

Executes a prepared non-query statement. Equivalent to Connection::execute — included for parity with the typed-row query() so callers who want Statement::run / Statement::query symmetry get it.

Errors if the prepared SQL contains ? placeholders — use Statement::execute_with_params for those.

pub fn execute_with_params(&mut self, params: &[Value]) -> Result<String>

SQLR-23 — executes a prepared non-SELECT statement after binding ? placeholders to params (positional, in source order).

Use this for parameterized INSERT / UPDATE / DELETE — the substitution clones the cached AST, fills in the ? slots from params, and dispatches without re-running sqlparser. For SELECT, prefer Statement::query_with_params.

pub fn query(&self) -> Result<Rows>

Runs a SELECT and returns a Rows iterator over typed rows. Errors if the prepared statement isn’t a SELECT.

SQLR-23 — uses the SELECT narrowing cached at prepare time; no per-call sqlparser walk. Errors if the prepared SQL contains ? placeholders — use Statement::query_with_params for those.

Examples found in repository

examples/hybrid-retrieval/hybrid_retrieval.rs (line 127)

fn print_top(conn: &mut Connection, sql: &str) -> Result<()> {
    let stmt = conn.prepare(sql)?;
    let mut rows = stmt.query()?;
    let mut rank = 1;
    while let Some(row) = rows.next()? {
        let name: String = row.get_by_name("name")?;
        let body: String = row.get_by_name("body")?;
        println!("  {rank}. {name}  \"{body}\"");
        rank += 1;
    }
    println!();
    Ok(())
}

examples/rust/concurrent_writers.rs (line 77)

fn print_balances(conn: &mut Connection) -> Result<()> {
    let stmt = conn.prepare("SELECT id, holder, balance FROM accounts ORDER BY id")?;
    let mut rows = stmt.query()?;
    while let Some(row) = rows.next()? {
        let id: i64 = row.get_by_name("id")?;
        let holder: String = row.get_by_name("holder")?;
        let balance: i64 = row.get_by_name("balance")?;
        println!("  account {id} ({holder}): {balance}");
    }
    Ok(())
}

examples/rust/quickstart.rs (line 24)

fn main() -> Result<()> {
    let mut conn = Connection::open_in_memory()?;

    conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER);")?;
    conn.execute("INSERT INTO users (name, age) VALUES ('alice', 30);")?;
    conn.execute("INSERT INTO users (name, age) VALUES ('bob', 25);")?;
    conn.execute("INSERT INTO users (name, age) VALUES ('charlie', 40);")?;

    println!("All users:");
    let stmt = conn.prepare("SELECT id, name, age FROM users;")?;
    let mut rows = stmt.query()?;
    while let Some(row) = rows.next()? {
        let id: i64 = row.get_by_name("id")?;
        let name: String = row.get_by_name("name")?;
        // `Option<i64>` wraps NULL cleanly — `age` is declared
        // nullable so the typed accessor surfaces None when absent.
        let age: Option<i64> = row.get_by_name("age")?;
        println!(
            "  {} — {} ({})",
            id,
            name,
            age.map(|a| a.to_string())
                .unwrap_or_else(|| "NULL".to_string())
        );
    }

    // Transactions: BEGIN + INSERT + ROLLBACK leaves the table untouched.
    conn.execute("BEGIN;")?;
    conn.execute("INSERT INTO users (name, age) VALUES ('will_vanish', 99);")?;
    println!("\nMid-transaction row count: {}", count_users(&mut conn)?);
    conn.execute("ROLLBACK;")?;
    println!(
        "Post-rollback row count:   {} (unchanged)",
        count_users(&mut conn)?
    );

    Ok(())
}

fn count_users(conn: &mut Connection) -> Result<usize> {
    let stmt = conn.prepare("SELECT id FROM users;")?;
    let rows = stmt.query()?.collect_all()?;
    Ok(rows.len())
}

pub fn query_with_params(&self, params: &[Value]) -> Result<Rows>

SQLR-23 — runs a SELECT and returns a Rows iterator after binding ? placeholders to params. Positional, source-order indexing — params[0] is ?1, params[1] is ?2, etc.

Vector parameters (Value::Vector(...)) substitute as the in-band bracket-array shape the executor recognizes, so a bound query vector still triggers the HNSW probe optimizer (Phase 7d.2 KNN shortcut).

pub fn column_names(&self) -> Option<Vec<String>>

Column names this statement will produce, in projection order. None for non-SELECT statements.

Trait Implementations

impl Debug for Statement<'_>

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

Formats the value using the given formatter.