Struct LocalClient

pub struct LocalClient { /* private fields */ }

The primary interface to the database.

Only one LocalClient can exist in each thread and transactions need to mutably borrow a LocalClient. This makes it impossible to have access to two transactions from one thread.

The only way to have concurrent read transactions is to have them on different threads. Write transactions never run in parallell with each other, but they do run in parallel with read transactions.

Implementations

impl LocalClient

pub fn migrator<'t, S: Schema>( &'t mut self, config: Config, ) -> Option<Migrator<'t, S>>

Create a Migrator to migrate a database.

Returns None if the database user_version on disk is older than S.

This function will panic if the schema on disk does not match what is expected for its user_version.

impl LocalClient

pub fn transaction<S>(&mut self, db: &Database<S>) -> Transaction<'_, S>

Create a Transaction. This operation always completes immediately as it does not need to wait on other transactions.

This function will panic if the schema was modified compared to when the Database value was created. This can happen for example by running another instance of your program with additional migrations.

pub fn transaction_mut<S>(&mut self, db: &Database<S>) -> TransactionMut<'_, S>

Create a TransactionMut. This operation needs to wait for all other TransactionMuts for this database to be finished.

The implementation uses the unlock_notify feature of sqlite. This makes it work across processes.

Note: you can create a deadlock if you are holding on to another lock while trying to get a mutable transaction!

This function will panic if the schema was modified compared to when the Database value was created. This can happen for example by running another instance of your program with additional migrations.

impl LocalClient

pub fn try_new() -> Option<Self>

Create a LocalClient if it was not created yet on this thread.

Async tasks often share their thread and can thus not use this method. Instead you should use your equivalent of spawn_blocking or block_in_place. These functions guarantee that you have a unique thread and thus allow LocalClient::try_new.

Note that using spawn_blocking for sqlite is actually a good practice. Sqlite queries can be expensive, it might need to read from disk which is slow. Doing so on all async runtime threads would prevent other tasks from executing.

Trait Implementations

impl Drop for LocalClient

fn drop(&mut self)

Dropping a LocalClient allows retrieving it with LocalClient::try_new again.