Struct diesel::prelude::SqliteConnection

source ·

pub struct SqliteConnection { /* private fields */ }

Expand description

Connections for the SQLite backend. Unlike other backends, SQLite supported connection URLs are:

File paths (test.db)
URIs (file://test.db)
Special identifiers (:memory:)

§Supported loading model implementations

DefaultLoadingMode

As SqliteConnection only supports a single loading mode implementation it is not required to explicitly specify a loading mode when calling RunQueryDsl::load_iter() or LoadConnection::load

§DefaultLoadingMode

SqliteConnection only supports a single loading mode, which loads values row by row from the result set.

use diesel::connection::DefaultLoadingMode;
{ // scope to restrict the lifetime of the iterator
    let iter1 = users::table.load_iter::<(i32, String), DefaultLoadingMode>(connection)?;

    for r in iter1 {
        let (id, name) = r?;
        println!("Id: {} Name: {}", id, name);
    }
}

// works without specifying the loading mode
let iter2 = users::table.load_iter::<(i32, String), _>(connection)?;

for r in iter2 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

This mode does not support creating multiple iterators using the same connection.

use diesel::connection::DefaultLoadingMode;

let iter1 = users::table.load_iter::<(i32, String), DefaultLoadingMode>(connection)?;
let iter2 = users::table.load_iter::<(i32, String), DefaultLoadingMode>(connection)?;

for r in iter1 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

for r in iter2 {
    let (id, name) = r?;
    println!("Id: {} Name: {}", id, name);
}

Implementations§

source §

impl SqliteConnection

source

pub fn immediate_transaction<T, E, F>(&mut self, f: F) -> Result<T, E>
where F: FnOnce(&mut Self) -> Result<T, E>, E: From<Error>,

Run a transaction with BEGIN IMMEDIATE

This method will return an error if a transaction is already open.

§Example

conn.immediate_transaction(|conn| {
    // Do stuff in a transaction
    Ok(())
})

source

pub fn exclusive_transaction<T, E, F>(&mut self, f: F) -> Result<T, E>
where F: FnOnce(&mut Self) -> Result<T, E>, E: From<Error>,

Run a transaction with BEGIN EXCLUSIVE

This method will return an error if a transaction is already open.

§Example

conn.exclusive_transaction(|conn| {
    // Do stuff in a transaction
    Ok(())
})

source

pub fn register_collation<F>( &mut self, collation_name: &str, collation: F, ) -> QueryResult<()>
where F: Fn(&str, &str) -> Ordering + Send + 'static + UnwindSafe,

Register a collation function.

collation must always return the same answer given the same inputs. If collation panics and unwinds the stack, the process is aborted, since it is used across a C FFI boundary, which cannot be unwound across and there is no way to signal failures via the SQLite interface in this case..

If the name is already registered it will be overwritten.

This method will return an error if registering the function fails, either due to an out-of-memory situation or because a collation with that name already exists and is currently being used in parallel by a query.

The collation needs to be specified when creating a table: CREATE TABLE my_table ( str TEXT COLLATE MY_COLLATION ), where MY_COLLATION corresponds to name passed as collation_name.

§Example

// sqlite NOCASE only works for ASCII characters,
// this collation allows handling UTF-8 (barring locale differences)
conn.register_collation("RUSTNOCASE", |rhs, lhs| {
    rhs.to_lowercase().cmp(&lhs.to_lowercase())
})

source

pub fn serialize_database_to_buffer(&mut self) -> SerializedDatabase

Serialize the current SQLite database into a byte buffer.

The serialized data is identical to the data that would be written to disk if the database was saved in a file.

§Returns

This function returns a byte slice representing the serialized database.

source

pub fn deserialize_readonly_database_from_buffer( &mut self, data: &[u8], ) -> QueryResult<()>

Deserialize an SQLite database from a byte buffer.

This function takes a byte slice and attempts to deserialize it into a SQLite database. If successful, the database is loaded into the connection. If the deserialization fails, an error is returned.

The database is opened in READONLY mode.

§Example

let connection = &mut SqliteConnection::establish(":memory:").unwrap();

sql_query("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")
    .execute(connection).unwrap();
sql_query("INSERT INTO users (name, email) VALUES ('John Doe', 'john.doe@example.com'), ('Jane Doe', 'jane.doe@example.com')")
    .execute(connection).unwrap();

// Serialize the database to a byte vector
let serialized_db: SerializedDatabase = connection.serialize_database_to_buffer();

// Create a new in-memory SQLite database
let connection = &mut SqliteConnection::establish(":memory:").unwrap();

// Deserialize the byte vector into the new database
connection.deserialize_readonly_database_from_buffer(serialized_db.as_slice()).unwrap();

Trait Implementations§

source §

impl Connection for SqliteConnection

source §

fn establish(database_url: &str) -> ConnectionResult<Self>

Establish a connection to the database specified by database_url.

See SqliteConnection for supported database_url.

If the database does not exist, this method will try to create a new database and then establish a connection to it.

source §

type Backend = Sqlite

The backend this type connects to

source §

fn set_instrumentation(&mut self, instrumentation: impl Instrumentation)

Set a specific Instrumentation implementation for this connection

source §

fn transaction<T, E, F>(&mut self, f: F) -> Result<T, E>
where F: FnOnce(&mut Self) -> Result<T, E>, E: From<Error>,

Executes the given function inside of a database transaction Read more

source §

fn begin_test_transaction(&mut self) -> QueryResult<()>

Creates a transaction that will never be committed. This is useful for tests. Panics if called while inside of a transaction or if called with a connection containing a broken transaction

source §