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")?;

Multiple connections (Phase 10.1)

Connection is a thin handle over an Arc<Mutex<Database>>. Call Connection::connect to mint a sibling handle that shares the same backing Database — typically one per worker thread. Today every operation still serializes through the single mutex (and the pager’s exclusive flock between processes), so the headline behaviour change is that callers can hold and address the same DB from more than one thread without wrapping the whole Connection in a Mutex themselves. BEGIN CONCURRENT and snapshot-isolated reads land in subsequent Phase 10 sub-phases.

Connection is Send + Sync. The recommended pattern is one connection per thread (clone via connect()); statements still borrow &mut Connection, so a single connection isn’t suitable for true concurrent statement execution.

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/rust/concurrent_writers.rs (line 22)

fn main() -> Result<()> {
    let mut a = Connection::open_in_memory()?;
    a.execute("PRAGMA journal_mode = mvcc")?;
    a.execute(
        "CREATE TABLE accounts (
             id      INTEGER PRIMARY KEY,
             holder  TEXT NOT NULL,
             balance INTEGER NOT NULL
         )",
    )?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (1, 'alice', 100)")?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (2, 'bob',   100)")?;

    // Sibling handle on the same Arc<Mutex<Database>>. In real apps
    // you'd hand this to a worker thread; we keep it on the main
    // thread to keep the demo readable.
    let mut b = a.connect();

    println!("=== Disjoint-row commits both succeed ===");
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 10 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 20 WHERE id = 2")?;
    a.execute("COMMIT")?;
    b.execute("COMMIT")?; // write-sets don't intersect — no conflict.
    print_balances(&mut a)?;

    println!("\n=== Same-row commits: A wins, B retries ===");
    // Interleave BEGINs so A.begin_ts < B.begin_ts and both see the
    // same pre-update value.
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 5 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
    a.execute("COMMIT")?;
    // B's commit sees a version newer than its own `begin_ts` → Busy.
    // The transaction is already dropped on the failed COMMIT;
    // there's no ROLLBACK to run. Start a fresh BEGIN CONCURRENT.
    match b.execute("COMMIT") {
        Err(e) if e.is_retryable() => {
            eprintln!("  B lost the race: {e}");
            b.execute("BEGIN CONCURRENT")?;
            b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
            b.execute("COMMIT")?;
        }
        other => {
            other?;
        }
    }
    print_balances(&mut a)?;

    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 connect(&self) -> Self

Phase 10.1 — mints another Connection sharing the same backing Database. Hand the returned handle to a separate thread to address the same in-memory tables and persistent pager from there.

The new handle starts with an empty prepared-statement cache (caches are per-handle, by design). Inherits the parent’s prepare_cached capacity. Concurrent operations still serialize through the engine’s internal lock and the pager’s existing single-writer rule — a true multi-writer story arrives with BEGIN CONCURRENT in Phase 10.4.

let mut primary = Connection::open("foo.sqlrite")?;
let secondary = primary.connect();
std::thread::spawn(move || {
    let mut conn = secondary;
    conn.execute("INSERT INTO t (x) VALUES (1)").unwrap();
})
.join()
.unwrap();

Examples found in repository

examples/rust/concurrent_writers.rs (line 37)

fn main() -> Result<()> {
    let mut a = Connection::open_in_memory()?;
    a.execute("PRAGMA journal_mode = mvcc")?;
    a.execute(
        "CREATE TABLE accounts (
             id      INTEGER PRIMARY KEY,
             holder  TEXT NOT NULL,
             balance INTEGER NOT NULL
         )",
    )?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (1, 'alice', 100)")?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (2, 'bob',   100)")?;

    // Sibling handle on the same Arc<Mutex<Database>>. In real apps
    // you'd hand this to a worker thread; we keep it on the main
    // thread to keep the demo readable.
    let mut b = a.connect();

    println!("=== Disjoint-row commits both succeed ===");
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 10 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 20 WHERE id = 2")?;
    a.execute("COMMIT")?;
    b.execute("COMMIT")?; // write-sets don't intersect — no conflict.
    print_balances(&mut a)?;

    println!("\n=== Same-row commits: A wins, B retries ===");
    // Interleave BEGINs so A.begin_ts < B.begin_ts and both see the
    // same pre-update value.
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 5 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
    a.execute("COMMIT")?;
    // B's commit sees a version newer than its own `begin_ts` → Busy.
    // The transaction is already dropped on the failed COMMIT;
    // there's no ROLLBACK to run. Start a fresh BEGIN CONCURRENT.
    match b.execute("COMMIT") {
        Err(e) if e.is_retryable() => {
            eprintln!("  B lost the race: {e}");
            b.execute("BEGIN CONCURRENT")?;
            b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
            b.execute("COMMIT")?;
        }
        other => {
            other?;
        }
    }
    print_balances(&mut a)?;

    Ok(())
}

pub fn handle_count(&self) -> usize

Phase 10.1 — number of Connection handles currently sharing this database (this handle plus every live connect() descendant). Useful for diagnostics and tests; no semantic guarantee beyond that.

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, BEGIN CONCURRENT). 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.

Phase 11.4 — intercepts BEGIN CONCURRENT, COMMIT, and ROLLBACK before sqlparser sees them so the per-connection MVCC transaction state stays in sync. Inside an open concurrent transaction, every other statement runs against the transaction’s private cloned tables; the live database stays untouched until commit-validation succeeds.

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

fn main() -> Result<()> {
    let mut a = Connection::open_in_memory()?;
    a.execute("PRAGMA journal_mode = mvcc")?;
    a.execute(
        "CREATE TABLE accounts (
             id      INTEGER PRIMARY KEY,
             holder  TEXT NOT NULL,
             balance INTEGER NOT NULL
         )",
    )?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (1, 'alice', 100)")?;
    a.execute("INSERT INTO accounts (id, holder, balance) VALUES (2, 'bob',   100)")?;

    // Sibling handle on the same Arc<Mutex<Database>>. In real apps
    // you'd hand this to a worker thread; we keep it on the main
    // thread to keep the demo readable.
    let mut b = a.connect();

    println!("=== Disjoint-row commits both succeed ===");
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 10 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 20 WHERE id = 2")?;
    a.execute("COMMIT")?;
    b.execute("COMMIT")?; // write-sets don't intersect — no conflict.
    print_balances(&mut a)?;

    println!("\n=== Same-row commits: A wins, B retries ===");
    // Interleave BEGINs so A.begin_ts < B.begin_ts and both see the
    // same pre-update value.
    a.execute("BEGIN CONCURRENT")?;
    b.execute("BEGIN CONCURRENT")?;
    a.execute("UPDATE accounts SET balance = balance + 5 WHERE id = 1")?;
    b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
    a.execute("COMMIT")?;
    // B's commit sees a version newer than its own `begin_ts` → Busy.
    // The transaction is already dropped on the failed COMMIT;
    // there's no ROLLBACK to run. Start a fresh BEGIN CONCURRENT.
    match b.execute("COMMIT") {
        Err(e) if e.is_retryable() => {
            eprintln!("  B lost the race: {e}");
            b.execute("BEGIN CONCURRENT")?;
            b.execute("UPDATE accounts SET balance = balance + 50 WHERE id = 1")?;
            b.execute("COMMIT")?;
        }
        other => {
            other?;
        }
    }
    print_balances(&mut a)?;

    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 execute_with_render(&mut self, sql: &str) -> Result<CommandOutput>

Phase 11.11a — same as Connection::execute, but returns the full [CommandOutput] (status + optional pre-rendered prettytable for SELECT). The REPL needs this to print the table the engine produced and the status line in one pass, while still routing BEGIN CONCURRENT / COMMIT / ROLLBACK through the per-connection MVCC state.

BEGIN / COMMIT / ROLLBACK carry no rendered output — they return CommandOutput { status, rendered: None }.

pub fn concurrent_tx_is_open(&self) -> bool

Phase 11.5 — cheap probe used by Connection::execute (and Statement::query) to decide whether to route through the concurrent-tx dispatch. Acquires the concurrent_tx mutex briefly; never blocks for a meaningful amount of time because the only other lockers are this connection’s own writers.

Public so the REPL can render per-handle tx state in .conns output (Phase 11.11a).

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/concurrent_writers.rs (line 76)

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 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-database runtime state — closing the last connection to a database 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.

pub fn journal_mode(&self) -> JournalMode

Phase 11.3 — current journal mode. Wal (default) keeps every pre-Phase-11 caller’s behaviour. Mvcc is opt-in via PRAGMA journal_mode = mvcc;. Per-database — every Connection::connect sibling sees the same value.

Today this is observable but doesn’t change query behaviour; 11.4 wires Mvcc mode into the read/write paths.

pub fn vacuum_mvcc(&self) -> usize

Phase 11.6 — explicit full-store MVCC garbage collection pass. Walks every row in the MvStore chain and drops versions whose end timestamp is below the current watermark (the smallest begin_ts across all in-flight transactions on this database, or u64::MAX when nothing is in flight).

Returns the number of versions reclaimed. Cheap when the store is small; a future optimisation will give it background-thread semantics behind a configurable cadence.

Per-commit GC already sweeps the rows each transaction touched, so most callers don’t need this — it’s the “vacuum the whole store” escape hatch for memory-pressure workloads or test suites that want a deterministic baseline. Safe to call even if journal_mode is Wal (the store is just empty); useful for tests that want to assert “no versions left.”

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.