Struct Connection 

pub struct Connection { /* private fields */ }

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).

Transactions

let mut conn = Connection::open("foo.sqlrite")?;
conn.execute("BEGIN")?;
conn.execute("INSERT INTO users (name) VALUES ('alice')")?;
conn.execute("INSERT INTO users (name) VALUES ('bob')")?;
conn.execute("COMMIT")?;

Connection is Send but not Sync — clone it (it’s currently unclonable) or share via a Mutex<Connection> if you need multi-threaded access.

Implementations

impl Connection

pub fn open<P: AsRef<Path>>(path: P) -> Result<Self>

Opens (or creates) a database file for read-write access.

If the file doesn’t exist, an empty one is materialized with the current format version. Takes an exclusive advisory lock on the file and its -wal sidecar; returns Err if either is already locked by another process.

pub fn open_read_only<P: AsRef<Path>>(path: P) -> Result<Self>

Opens an existing database file for read-only access. Takes a shared advisory lock, so multiple read-only connections can coexist on the same file; any open writer excludes them. Mutating statements return cannot execute: database is opened read-only.

pub fn open_in_memory() -> Result<Self>

Opens a transient in-memory database. No file is touched and no locks are taken; state lives for the lifetime of the Connection and is discarded on drop.

Examples found in repository

examples/rust/quickstart.rs (line 15)

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(())
}

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

fn main() -> Result<()> {
    let mut conn = Connection::open_in_memory()?;
    conn.execute(
        "CREATE TABLE docs (id INTEGER PRIMARY KEY, name TEXT, body TEXT, embedding VECTOR(4));",
    )?;
    for (name, body, vec) in CORPUS {
        conn.execute(&format!(
            "INSERT INTO docs (name, body, embedding) VALUES \
             ('{name}', '{body}', [{}, {}, {}, {}]);",
            vec[0], vec[1], vec[2], vec[3]
        ))?;
    }
    conn.execute("CREATE INDEX docs_fts ON docs USING fts (body);")?;

    // Same query, three rankings — see README for what each shape sees.
    let body_query = "small embedded database";
    let vector_query = [0.0, 0.0, 0.9, 0.2]; // semantic intent: "database, lightly web-ish"
    let q_str = vec_lit(&vector_query);

    println!("Corpus:");
    for (name, body, vec) in CORPUS {
        println!("  {name}: \"{body}\"  embedding={vec:?}");
    }
    println!("\nQuery body:   '{body_query}'");
    println!("Query vector: {vector_query:?}\n");

    println!("===  1. Pure BM25 (lexical) ===");
    println!(
        "WHERE  fts_match(body, '{body_query}')\n\
         ORDER BY bm25_score(body, '{body_query}') DESC  LIMIT 3"
    );
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             WHERE fts_match(body, '{body_query}') \
             ORDER BY bm25_score(body, '{body_query}') DESC LIMIT 3;"
        ),
    )?;

    println!("===  2. Pure vector (semantic) ===");
    println!("ORDER BY vec_distance_cosine(embedding, {q_str}) ASC  LIMIT 3");
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             ORDER BY vec_distance_cosine(embedding, {q_str}) ASC LIMIT 3;"
        ),
    )?;

    println!("===  3. Hybrid (50% BM25 + 50% inverted cosine) ===");
    println!(
        "WHERE  fts_match(body, '{body_query}')\n\
         ORDER BY 0.5*bm25_score(...) + 0.5*(1.0 - vec_distance_cosine(...)) DESC  LIMIT 3"
    );
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             WHERE fts_match(body, '{body_query}') \
             ORDER BY 0.5 * bm25_score(body, '{body_query}') \
                    + 0.5 * (1.0 - vec_distance_cosine(embedding, {q_str})) DESC \
             LIMIT 3;"
        ),
    )?;
    Ok(())
}

pub fn execute(&mut self, sql: &str) -> Result<String>

Parses and executes one SQL statement. For DDL (CREATE TABLE, CREATE INDEX), DML (INSERT, UPDATE, DELETE) and transaction control (BEGIN, COMMIT, ROLLBACK). Returns the status message the engine produced (e.g. "INSERT Statement executed.").

For SELECT, execute works but discards the row data and just returns the rendered status — use Connection::prepare and Statement::query to iterate typed rows.

Examples found in repository

examples/rust/quickstart.rs (line 17)

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(())
}

examples/hybrid-retrieval/hybrid_retrieval.rs (lines 54-56)

fn main() -> Result<()> {
    let mut conn = Connection::open_in_memory()?;
    conn.execute(
        "CREATE TABLE docs (id INTEGER PRIMARY KEY, name TEXT, body TEXT, embedding VECTOR(4));",
    )?;
    for (name, body, vec) in CORPUS {
        conn.execute(&format!(
            "INSERT INTO docs (name, body, embedding) VALUES \
             ('{name}', '{body}', [{}, {}, {}, {}]);",
            vec[0], vec[1], vec[2], vec[3]
        ))?;
    }
    conn.execute("CREATE INDEX docs_fts ON docs USING fts (body);")?;

    // Same query, three rankings — see README for what each shape sees.
    let body_query = "small embedded database";
    let vector_query = [0.0, 0.0, 0.9, 0.2]; // semantic intent: "database, lightly web-ish"
    let q_str = vec_lit(&vector_query);

    println!("Corpus:");
    for (name, body, vec) in CORPUS {
        println!("  {name}: \"{body}\"  embedding={vec:?}");
    }
    println!("\nQuery body:   '{body_query}'");
    println!("Query vector: {vector_query:?}\n");

    println!("===  1. Pure BM25 (lexical) ===");
    println!(
        "WHERE  fts_match(body, '{body_query}')\n\
         ORDER BY bm25_score(body, '{body_query}') DESC  LIMIT 3"
    );
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             WHERE fts_match(body, '{body_query}') \
             ORDER BY bm25_score(body, '{body_query}') DESC LIMIT 3;"
        ),
    )?;

    println!("===  2. Pure vector (semantic) ===");
    println!("ORDER BY vec_distance_cosine(embedding, {q_str}) ASC  LIMIT 3");
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             ORDER BY vec_distance_cosine(embedding, {q_str}) ASC LIMIT 3;"
        ),
    )?;

    println!("===  3. Hybrid (50% BM25 + 50% inverted cosine) ===");
    println!(
        "WHERE  fts_match(body, '{body_query}')\n\
         ORDER BY 0.5*bm25_score(...) + 0.5*(1.0 - vec_distance_cosine(...)) DESC  LIMIT 3"
    );
    print_top(
        &mut conn,
        &format!(
            "SELECT name, body FROM docs \
             WHERE fts_match(body, '{body_query}') \
             ORDER BY 0.5 * bm25_score(body, '{body_query}') \
                    + 0.5 * (1.0 - vec_distance_cosine(embedding, {q_str})) DESC \
             LIMIT 3;"
        ),
    )?;
    Ok(())
}

pub fn prepare<'c>(&'c mut self, sql: &str) -> Result<Statement<'c>>

Prepares a statement for repeated execution or row iteration. SQLR-23: the SQL is parsed once at prepare time (sqlparser walk plus placeholder rewriting), and the resulting AST is cached on the Statement for re-execution without further parsing.

Use Statement::query / Statement::run for unbound execution, or Statement::query_with_params / Statement::execute_with_params to substitute ? placeholders.

Examples found in repository

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

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/quickstart.rs (line 23)

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 prepare_cached<'c>(&'c mut self, sql: &str) -> Result<Statement<'c>>

Same as Connection::prepare, but consults a small per-connection LRU first. SQLR-23 — for hot statements (the body of an INSERT loop, a frequently-rerun lookup) the sqlparser walk is amortized to once across the connection’s lifetime, not once per prepare().

Default cache capacity is 16; tune with Connection::set_prepared_cache_capacity.

pub fn set_prepared_cache_capacity(&mut self, cap: usize)

SQLR-23 — sets the maximum number of cached prepared plans (matches prepare_cached’s default 16). Reducing below the current size evicts the oldest entries; setting to 0 disables caching but prepare_cached still works (it just always re-parses).

pub fn prepared_cache_len(&self) -> usize

SQLR-23 — current number of plans held by the prepared-statement cache. Useful for tests / introspection; not load-bearing for the public API.

pub fn in_transaction(&self) -> bool

Returns true while a BEGIN … COMMIT/ROLLBACK block is open against this connection.

pub fn auto_vacuum_threshold(&self) -> Option<f32>

Returns the current auto-VACUUM threshold (SQLR-10). After a page-releasing DDL (DROP TABLE / DROP INDEX / ALTER TABLE DROP COLUMN) commits, the engine compacts the file in place if the freelist exceeds this fraction of page_count. New connections default to Some(0.25) (SQLite parity); None means the trigger is disabled. See Connection::set_auto_vacuum_threshold.

pub fn set_auto_vacuum_threshold( &mut self, threshold: Option<f32>, ) -> Result<()>

Sets the auto-VACUUM threshold (SQLR-10). Some(t) with t in 0.0..=1.0 arms the trigger; None disables it. Values outside 0.0..=1.0 (or NaN / infinite) return a typed error rather than silently saturating. The setting is per-connection runtime state — closing the connection drops it; new connections start at the default Some(0.25).

Calling this on an in-memory or read-only database is allowed (it just won’t fire — there’s nothing to compact / no writes will reach the trigger).

pub fn is_read_only(&self) -> bool

Returns true if the connection was opened read-only. Mutating statements on a read-only connection return a typed error.

Trait Implementations

impl ConnectionAskExt for Connection

Available on crate feature ask only.

fn ask( &self, question: &str, config: &AskConfig, ) -> Result<AskResponse, AskError>

Generate SQL from a natural-language question.

impl Debug for Connection

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

Formats the value using the given formatter.