Struct Connection 

pub struct Connection { /* private fields */ }

A database connection. Supports reading (query) and writing (execute), over a file or in memory.

Implementations

impl Connection

pub fn open_vfs(vfs: &dyn Vfs, path: &str) -> Result<Connection>

Open an existing database for reading and writing through vfs. Creates (and recovers from) a <path>-journal companion file.

pub fn open_readonly_vfs(vfs: &dyn Vfs, path: &str) -> Result<Connection>

Open an existing database read-only through vfs. If a <path>-wal file is present, its committed frames are overlaid so WAL-mode databases read correctly.

pub fn create_vfs( vfs: &dyn Vfs, path: &str, page_size: u32, ) -> Result<Connection>

Create a new, empty database through vfs.

pub fn open(path: &str) -> Result<Connection>

Available on crate feature std only.

Open an existing database file for reading and writing (requires std).

pub fn open_readonly(path: &str) -> Result<Connection>

Available on crate feature std only.

Open an existing database file read-only (requires std).

pub fn create(path: &str) -> Result<Connection>

Available on crate feature std only.

Create a new database file with the default 4096-byte page size (std).

pub fn open_memory() -> Result<Connection>

Create a fresh in-memory database (:memory:), always available.

pub fn schema(&self) -> &Schema

The schema catalog.

pub fn query(&self, sql: &str) -> Result<QueryResult>

Run a single SELECT and return all rows.

pub fn query_vdbe(&self, sql: &str) -> Result<QueryResult>

Run sql through the experimental VDBE engine instead of the tree-walker. Supports constant projections and plain single-table scans (SELECT <exprs> FROM <table> with no WHERE/joins/aggregates/ORDER BY); returns Unsupported otherwise so callers can fall back to query.

pub fn set_use_vdbe(&self, on: bool)

Enable or disable the VDBE engine for SELECT (Track B). When on (the default), query runs through the VDBE and falls back transparently to the tree-walker for any query shape it does not handle; turning it off forces the tree-walker. The result is identical either way.

pub fn query_params(&self, sql: &str, params: &Params) -> Result<QueryResult>

Like query but with bound parameters.

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

Execute a single non-SELECT statement, returning the number of rows affected (0 for DDL and transaction control).

pub fn register_module( &mut self, name: &str, module: impl DynVTabModule + 'static, ) -> Result<()>

Register a virtual-table module under name, the identifier used after USING in CREATE VIRTUAL TABLE … USING <name>. A module implementing VTabModule::update makes its tables writable; the default leaves them read-only. Fails if a module is already registered under that name (case-insensitively).

pub fn register_function( &mut self, name: &str, f: impl Fn(&[Value]) -> Result<Value> + 'static, )

Register a user-defined scalar function callable from SQL by name. f receives the evaluated argument values and returns a result Value. A built-in function of the same name takes precedence; registering an existing user function replaces it. The callback should validate its own argument count and types (returning an error otherwise), like SQLite’s sqlite3_create_function callbacks.

pub fn register_aggregate_function( &mut self, name: &str, factory: impl Fn() -> Box<dyn AggregateFunction> + 'static, )

Register a user-defined aggregate function callable from SQL by name. factory builds a fresh AggregateFunction accumulator for each group; the engine calls step once per group row (with the evaluated arguments) then finalize. Built-in aggregates of the same name take precedence.

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

Execute a ;-separated script of one or more statements, like SQLite’s sqlite3_exec. Each statement runs in order through the normal single-statement path (so per-statement CREATE text is preserved and each autocommits unless the script opens its own transaction); execution stops at the first error. ; inside string literals, --//* */ comments, and BEGIN…END / CASE…END blocks does not split a statement. A SELECT runs and its rows are discarded (as sqlite3_exec does without a callback). execute stays single-statement.

pub fn execute_params(&mut self, sql: &str, params: &Params) -> Result<usize>

Like execute but with bound parameters.

pub fn execute_returning( &mut self, sql: &str, params: &Params, ) -> Result<QueryResult>

Execute an INSERT/UPDATE/DELETE with a RETURNING clause, returning the projected rows as a QueryResult. Without a RETURNING list the result has no columns and no rows (the statement still runs for its effects). Errors on SELECT/DDL — use query or execute for those.

Trait Implementations

impl Subqueries for Connection

fn last_insert_rowid(&self) -> i64

last_insert_rowid() — rowid of the most recently inserted row.

fn changes(&self) -> i64

changes() — rows modified by the most recent INSERT/UPDATE/DELETE.

fn total_changes(&self) -> i64

total_changes() — rows modified since the connection opened.

fn case_sensitive_like(&self) -> bool

Whether PRAGMA case_sensitive_like is ON for this connection, making the LIKE operator and the like() function compare ASCII case-sensitively (GLOB is always case-sensitive regardless). Default false — SQLite’s case-insensitive default — for the rowless/connection-less contexts.

fn next_random(&self) -> i64

One pseudo-random i64, advancing the connection’s generator — backs random() and randomblob(). The default (no connection in scope, e.g. rowless constant evaluation) is a fixed 0.

fn call_udf(&self, name: &str, args: &[Value]) -> Option<Result<Value>>

Invoke a user-defined scalar function registered on the connection (via Connection::register_function) with its evaluated argument values. Returns None when no function is registered under name (lowercased), so the caller can fall back to “no such function”. The default is None.

fn fts5_bm25(&self, rowid: i64, weights: &[f64]) -> Option<f64>

The FTS5 relevance score (bm25() / rank) of the row with this rowid, with optional per-column weights (empty → all 1.0), when the current query is a full-text MATCH over an fts5 table. None otherwise (so bm25()/rank fall back to the usual unknown-name error).

fn fts5_rank(&self, rowid: i64) -> Option<Result<f64>>

The FTS5 bare rank column’s value for the row with this rowid: the table’s configured default ranking function (set via INSERT INTO t(t, rank) VALUES('rank', …)), or the default bm25() when unconfigured. None when no MATCH over an fts5 table is in scope (so rank falls back to the usual unknown-column error); Some(Err) when the configured rank function is invalid (e.g. nosuchfunc()), matching SQLite’s deferred no such function / arity error at query time.

fn fts5_highlight( &self, col: usize, text: &str, open: &str, close: &str, ) -> Option<String>

FTS5 highlight(t, col, open, close): column col’s text with each matched token wrapped in open…close, when a MATCH over an fts5 table is in scope. None otherwise.

fn fts5_indexed_columns(&self, table: &str) -> Option<Vec<String>>

The searchable (indexed) column names of the fts5 table table, i.e. every declared column except those marked UNINDEXED. None when table is not a known fts5 virtual table (so callers fall back to all columns).

fn fts5_contentless_match( &self, table: &str, query: &str, rowid: i64, ) -> Option<bool>

Available on crate feature fts5 only.

Whether the document with rowid matches the full-text query in the contentless fts5 table table, evaluated against the inverted index (a contentless row keeps no column text, so MATCH can’t be re-checked from the row like it is for a self/external-content table). Returns None when table is not a contentless fts5 table (so the caller uses the column-text path); Some(true)/Some(false) when it is.

fn fts5_is_contentless_table(&self, table: &str) -> bool

Available on crate feature fts5 only.

Whether table is a contentless (content='') fts5 table. Used by highlight/snippet to return NULL (a contentless table stores no text to render). false for a non-fts5 or non-contentless table.

fn fts5_tok(&self, table: &str) -> Fts5Tok

Available on crate feature fts5 only.

The fts5 table table’s resolved tokenizer config (Porter stemming + remove_diacritics level), so a MATCH query folds exactly like the indexed documents. The default (remove_diacritics 1, no stemming) is returned when table is not a known fts5 virtual table.

fn fts5_snippet( &self, col: i64, cols: &[String], open: &str, close: &str, ellipsis: &str, ntokens: usize, ) -> Option<String>

FTS5 snippet(t, col, open, close, ellipsis, n): an up-to-n-token window of text covering the query’s phrases, matched tokens wrapped and trimmed ends marked with ellipsis, when a MATCH over an fts5 table is in scope. None otherwise.

fn scalar(&self, select: &Select, outer: &EvalCtx<'_>) -> Result<Value>

First column of the first row (NULL if no rows) — a scalar subquery. The enclosing row context outer is made available so correlated subqueries can resolve outer columns.

fn column(&self, select: &Select, outer: &EvalCtx<'_>) -> Result<Vec<Value>>

First column of every row — the candidate set for IN (SELECT …).

fn column_affinity(&self, select: &Select) -> Option<Affinity>

The declared affinity of the subquery’s first output column, for applying IN (SELECT …) comparison affinity. None when it has no affinity (a computed expression) or cannot be determined.

fn row_column_affinities(&self, select: &Select) -> Vec<Option<Affinity>>

The declared affinity of each of the subquery’s output columns, for a row-value (a, b, …) IN (SELECT …). Same per-column rule as Self::column_affinity; the vector may be empty if it cannot be determined.

fn rows(&self, select: &Select, outer: &EvalCtx<'_>) -> Result<Vec<Vec<Value>>>

Every row in full — the candidate set for a row-value (a,b) IN (SELECT …).

fn exists(&self, select: &Select, outer: &EvalCtx<'_>) -> Result<bool>

Whether the subquery returns at least one row — for EXISTS.

fn resolve_outer(&self, table: Option<&str>, name: &str) -> Option<Value>

Resolve a column against the enclosing (outer) query rows, if any are in scope. Returns None when there is no such outer column.

fn resolve_outer_affinity( &self, table: Option<&str>, name: &str, ) -> Option<Affinity>

The declared affinity of an outer (correlated) column, mirroring Self::resolve_outer. A correlated reference carries its source column’s affinity, so a comparison against it in the subquery applies the correct (two-column) comparison affinity — e.g. text_col = outer_untyped_col uses BLOB (no coercion), not the TEXT-coerce-the-literal rule. None when there is no such outer column.