Struct Database

Source

pub struct Database { /* private fields */ }

Expand description

Represents an owned connection to an SQLite database.

This struct is an owned version of Connection. When this struct is dropped, it will close the underlying connection to SQLite.

Implementations§

Source §

impl Database

Source

pub fn open<P: AsRef<Path>>(path: P) -> Result<Database>

Source

pub fn open_with_flags<P: AsRef<Path>>( path: P, flags: OpenFlags, ) -> Result<Database>

Source

pub fn close(self) -> Result<(), (Error, Database)>

Gracefully close the database. This automatically happens when the Database is dropped, but a failure in drop will result in a panic, while this method provides a path for graceful error handling.

Methods from Deref<Target = Connection>§

Source

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.

Source

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.

Source

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.

Source

pub fn dump_prepared_statements(&self)

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

Source

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.

Source

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.

Source

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.

Source

pub fn create_legacy_aggregate_function<U, F: LegacyAggregateFunction>( &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.

Source

pub fn create_aggregate_function<U, F: AggregateFunction>( &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.

Source

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.

Source

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

Register a new collating sequence.

Source

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.

Source

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.

Source

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.

Source