Struct Connection

pub struct Connection { /* private fields */ }

Represents a borrowed connection to an SQLite database.

Implementations

impl Connection

pub unsafe fn from_ptr<'a>(db: *mut sqlite3) -> &'a mut Connection

Convert an SQLite handle into a reference to Connection.

Safety

The behavior of this method is undefined if the passed pointer is not valid.

pub unsafe fn as_mut_ptr(&self) -> *mut sqlite3

Get the underlying SQLite handle.

Safety

Using the returned pointer may cause undefined behavior in other, safe code.

pub fn load_extension(&self, path: &str, entry: Option<&str>) -> Result<()>

Load the extension at the given path, optionally providing a specific entry point.

Safety

Loading libraries can cause undefined behavior in safe code. It is the caller’s responsibility to ensure that the extension is compatible with sqlite3_ext. In particular, the caller must verify that the extension being loaded (and the entry point being invoked) is actually an SQLite extension (created with sqlite3_ext or otherwise). Never invoke this method with untrusted user-specified data.

If extension loading is not enabled when this method is called and SQLite is at least version 3.13.0, then extension loading will temporarily be enabled before loading the extension, and disabled afterwards. On older versions of SQLite, extension loading must be manually enabled using unsafe ffi functions before this method can be used, see sqlite3_enable_load_extension for details.

Requires SQLite 3.8.7.

pub fn db_config_defensive(&self, enable: bool) -> Result<()>

Enable or disable the “defensive” flag for the database.

See SQLITE_DBCONFIG_DEFENSIVE for details.

Requires SQLite 3.26.0. On earlier versions, this method is a no-op.

pub fn dump_prepared_statements(&self)

Prints the text of all currently prepared statements to stderr. Intended for debugging.

impl Connection

pub fn create_overloaded_function( &self, name: &str, opts: &FunctionOptions, ) -> Result<()>

Create a stub function that always fails.

This API makes sure a global version of a function with a particular name and number of parameters exists. If no such function exists before this API is called, a new function is created. The implementation of the new function always causes an exception to be thrown. So the new function is not good for anything by itself. Its only purpose is to be a placeholder function that can be overloaded by a virtual table.

For more information, see vtab::FindFunctionVTab.

pub fn create_scalar_function<F>( &self, name: &str, opts: &FunctionOptions, func: F, ) -> Result<()>

where F: Fn(&Context, &mut [&mut ValueRef]) -> Result<()> + 'static,

Create a new scalar function. The function will be invoked with a Context and an array of ValueRef objects. The function is required to set its output using Context::set_result. If no result is set, SQL NULL is returned. If the function returns an Err value, the SQL statement will fail, even if a result had been set before the failure.

Compatibility

On versions of SQLite earlier than 3.7.3, this function will leak the function and all bound variables. This is because these versions of SQLite did not provide the ability to specify a destructor function.

pub fn create_legacy_aggregate_function<U, F: LegacyAggregateFunction<U>>( &self, name: &str, opts: &FunctionOptions, user_data: U, ) -> Result<()>

Create a new aggregate function which cannot be used as a window function.

In general, you should use create_aggregate_function instead, which provides all of the same features as legacy aggregate functions but also support WINDOW.

Compatibility

On versions of SQLite earlier than 3.7.3, this function will leak the user data. This is because these versions of SQLite did not provide the ability to specify a destructor function.

pub fn create_aggregate_function<U, F: AggregateFunction<U>>( &self, name: &str, opts: &FunctionOptions, user_data: U, ) -> Result<()>

Create a new aggregate function.

Compatibility

Window functions require SQLite 3.25.0. On earlier versions of SQLite, this function will automatically fall back to create_legacy_aggregate_function.

pub fn remove_function(&self, name: &str, n_args: i32) -> Result<()>

Remove an application-defined scalar or aggregate function. The name and n_args parameters must match the values used when the function was created.

pub fn create_collation<F: Fn(&str, &str) -> Ordering>( &self, name: &str, func: F, ) -> Result<()>

Register a new collating sequence.

pub fn set_collation_needed_func<F: Fn(&str)>(&self, func: F) -> Result<()>

Register a callback for when SQLite needs a collation sequence. The function will be invoked when a collation sequence is needed, and create_collation can be used to provide the needed sequence.

Note: the provided function and any captured variables will be leaked. SQLite does not provide any facilities for cleaning up this data.

impl Connection

pub fn lock(&self) -> SQLiteMutexGuard<'_, Connection>

Locks the mutex associated with this database connection. If multiple SQLite APIs need to be used and there is a chance that this Connection may be used from multiple threads, this method should be used to lock the Connection to the calling thread. The returned mutex guard will unlock the mutex when it is dropped, and derefs to the original connection.

This method has no effect if SQLite is not operating in serialized threading mode.

impl Connection

pub fn prepare_first<'a>( &self, sql: &'a str, ) -> Result<(Option<Statement>, &'a str)>

Prepare some SQL for execution. This method will return the prepared statement and a slice containing the portion of the original input which was after the first SQL statement.

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

Prepare some SQL for execution. This method will return Err(SQLITE_MISUSE) if the input string does not contain any SQL statements.

pub fn query<P>(&self, sql: &str, params: P) -> Result<Statement>

where P: Params,

Convenience method to prepare a query and bind it with values. See Statement::query.

pub fn query_row<P, R, F>(&self, sql: &str, params: P, f: F) -> Result<R>

where P: Params, F: FnOnce(&mut QueryResult) -> Result<R>,

Convenience method for self.prepare(sql)?.query_row(params, f). See Statement::query_row.

pub fn execute<P: Params>(&self, sql: &str, params: P) -> Result<i64>

Convenience method for self.prepare(sql)?.execute(params). See Statement::execute.

pub fn insert<P: Params>(&self, sql: &str, params: P) -> Result<i64>

Convenience method for self.prepare(sql)?.insert(params). See Statement::insert.

impl Connection

pub fn transaction(&self, tt: TransactionType) -> Result<Transaction<'_>>

Starts a new transaction with the specified behavior.

impl Connection

pub fn create_module<'db: 'vtab, 'vtab, T: VTab<'vtab> + 'vtab, M: Module<'vtab, T> + 'vtab>( &'db self, name: &str, vtab: M, aux: T::Aux, ) -> Result<()>

where T::Aux: 'db,

Register the provided virtual table module with this connection.

impl Connection

pub fn from_rusqlite(conn: &Connection) -> &Self

Available on crate feature with_rusqlite only.

Convert a rusqlite::Connection to an sqlite3_ext::Connection.

Trait Implementations

impl Debug for Connection

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

Formats the value using the given formatter.