Module connection

Expand description

Public Connection / Statement / Rows / Row API (Phase 5a + SQLR-23).

This is the stable surface external consumers bind against — Rust callers use it directly, language SDKs (Python, Node.js, Go) bind against the C FFI wrapper over these same types in Phase 5b, and the WASM build in Phase 5g re-exposes them via wasm-bindgen.

The shape mirrors rusqlite / Python’s sqlite3 so users familiar with either can pick it up immediately:

use sqlrite::Connection;

let mut conn = Connection::open("foo.sqlrite")?;
conn.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")?;
conn.execute("INSERT INTO users (name) VALUES ('alice')")?;

let mut stmt = conn.prepare("SELECT id, name FROM users")?;
let mut rows = stmt.query()?;
while let Some(row) = rows.next()? {
    let id: i64 = row.get(0)?;
    let name: String = row.get(1)?;
    println!("{id}: {name}");
}

Relationship to the internal engine. A Connection owns a Database (which owns a Pager for file-backed connections). execute and query go through the same process_command pipeline the REPL uses, just with typed row return instead of pre-rendered tables. The internal Database / Pager stay accessible via sqlrite::sql::... for the engine’s own tests and for the desktop app — but those paths aren’t considered stable API.

§Prepared statements & parameter binding (SQLR-23)

Connection::prepare parses the SQL once and stashes the AST on the returned Statement. Subsequent calls to Statement::query / Statement::run execute against the cached AST without re-running sqlparser. Bound versions (Statement::query_with_params / Statement::execute_with_params) accept a &[Value] slice that is substituted into the cached AST at execute time — including Value::Vector(...) for HNSW-eligible KNN queries, where binding the query vector skips per-iter lexing of the 4 KB bracket-array literal.

Connection::prepare_cached adds a small per-connection LRU (default cap 16) so a hot SQL string is parsed exactly once across every call, not once per prepare(). Matches the rusqlite pattern.

Structs§

Connection: A handle to a SQLRite database. Opens a file or an in-memory DB; drop it to close. Every mutating statement auto-saves (except inside an explicit BEGIN/COMMIT block — see Transactions).
OwnedRow: A row detached from the Rows iterator — owns its data, no borrow ties it to the parent iterator.
Row: A single row borrowed from a Rows iterator. Lives only as long as the iterator; call Row::to_owned_row to detach it if you need to keep it past the next next() call.
Rows: Iterator of typed Row values produced by a SELECT query.
Statement: A prepared statement bound to a specific connection lifetime.

Traits§

FromValue: Conversion from SQLRite’s internal Value enum into a typed Rust value. Implementations cover the common built-ins — i64, f64, String, bool, and Option<T> for nullable columns. Extend on demand.