Struct DbConnection 

pub struct DbConnection { /* private fields */ }

Database connection wrapper with migration support.

Implementations

impl DbConnection

pub fn open<P: AsRef<Path>>( path: P, db_type: DbType, ) -> Result<Self, ConnectionError>

Opens a database connection and runs migrations.

Arguments

• path - Path to the SQLite database file
• db_type - Type of database for selecting correct migrations

Errors

Returns an error if the connection fails or migrations fail.

pub fn open_without_migrations<P: AsRef<Path>>( path: P, ) -> Result<Self, ConnectionError>

Opens a database connection without running migrations.

Use this when you know the database is already migrated.

pub fn open_metadata<P: AsRef<Path>>(path: P) -> Result<Self, ConnectionError>

Opens a metadata database and migrates JSON text columns to JSONB.

This is used for metadata databases that are generated externally (e.g., by rusqlite) and may contain JSON stored as text instead of JSONB binary format.

Does NOT run schema migrations since the schema is managed externally.

pub fn conn(&mut self) -> &mut SqliteConnection

Gets a mutable reference to the underlying connection.

Methods from Deref<Target = SqliteConnection>

pub fn immediate_transaction<T, E, F>(&mut self, f: F) -> Result<T, E>

where F: FnOnce(&mut SqliteConnection) -> 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(())
})

pub fn exclusive_transaction<T, E, F>(&mut self, f: F) -> Result<T, E>

where F: FnOnce(&mut SqliteConnection) -> 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(())
})

pub fn register_collation<F>( &mut self, collation_name: &str, collation: F, ) -> Result<(), Error>

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())
})

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.

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

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

impl Deref for DbConnection

type Target = SqliteConnection

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for DbConnection

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.