Struct Transaction 

pub struct Transaction<'db> { /* private fields */ }

A RAII wrapper around transactions.

The transaction can be created using Connection::transaction, and finalized using commit or rollback. If no finalization method is used, the transaction will automatically be rolled back when it is dropped. For convenience, Transaction derefs to Connection.

Note that transactions affect the entire database connection. If other threads need to be prevented from interfering with a transaction, Connection::lock should be used.

This interface is optional. It’s permitted to execute BEGIN, COMMIT, and ROLLBACK statements directly, without using this interface. This interface

Implementations

impl<'db> Transaction<'db>

pub fn commit(self) -> Result<&'db Connection>

Consumes the Transaction, committing it.

pub fn rollback(self) -> Result<&'db Connection>

Consumes the Transaction, rolling it back.

pub fn savepoint(&mut self) -> Result<Transaction<'_>>

Create a savepoint for the current transaction. This functions identically to a transaction, but committing or rolling back will only affect statements since the savepoint was created.

Methods from Deref<Target = Connection>

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.

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.

The passed function can be a closure, however the lifetime of the closure must be 'static due to limitations in the Rust borrow checker. The Self::create_scalar_function_object function is an alternative that allows using an alternative lifetime.

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_scalar_function_object<'db, F>( &'db self, name: &str, opts: &FunctionOptions, func: F, ) -> Result<()>

where F: ScalarFunction<'db>,

Create a new scalar function using a struct. This function is identical to Self::create_scalar_function, but uses a trait object instead of a closure. This enables creating scalar functions that maintain references with a lifetime smaller than 'static.

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.

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.

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.

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

Starts a new transaction with the specified behavior.

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.

Trait Implementations

impl<'db> Debug for Transaction<'db>

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

Formats the value using the given formatter.

impl Deref for Transaction<'_>

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Connection

Dereferences the value.

impl Drop for Transaction<'_>

fn drop(&mut self)

Executes the destructor for this type.