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. The SQL is parsed once and validated; the resulting Statement can be executed multiple times. Today this is primarily useful for SELECT (to reach the typed-row API); parameter binding and prepared-plan caching are future work.

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 in_transaction(&self) -> bool

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

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.