Struct Database 

pub struct Database<S> { /* private fields */ }

Database is a proof that the database has been configured.

Creating a Database requires going through the steps to migrate an existing database to the required schema, or creating a new database from scratch (See also crate::migration::Config). Please see Database::migrator to get started.

Having done the setup to create a compatible database is sadly not a guarantee that the database will stay compatible for the lifetime of the Database struct. That is why Database also stores the schema_version. This allows detecting non-malicious modifications to the schema and gives us the ability to panic when this is detected. Such non-malicious modification of the schema can happen for example if another Database instance is created with additional migrations (e.g. by another newer instance of your program).

Implementations

impl<S: Schema> Database<S>

pub fn migrator(config: Config) -> Option<Migrator<S>>

Create a Migrator to migrate a database.

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

impl<S: Send + Sync + Schema> Database<S>

pub fn transaction<R: Send>( &self, f: impl Send + FnOnce(&'static Transaction<S>) -> R, ) -> R

Create a Transaction. Creating the transaction will not block by default.

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.

Note that many systems have a limit on the number of file descriptors that can exist in a single process. On my machine the soft limit is (1024) by default. If this limit is reached, it may cause a panic in this method.

pub fn transaction_mut<O: Send, E: Send>( &self, f: impl Send + FnOnce(&'static mut Transaction<S>) -> Result<O, E>, ) -> Result<O, E>

Create a mutable Transaction. This operation needs to wait for all other mutable Transactions for this database to be finished. There is currently no timeout on this operation, so it will wait indefinitly if required.

Whether the transaction is commited depends on the result of the closure. The transaction is only commited if the closure return Ok. In the case that it returns Err or when the closure panics, a rollback is performed.

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.

Note that many systems have a limit on the number of file descriptors that can exist in a single process. On my machine the soft limit is (1024) by default. If this limit is reached, it may cause a panic in this method.

pub fn transaction_mut_ok<R: Send>( &self, f: impl Send + FnOnce(&'static mut Transaction<S>) -> R, ) -> R

Same as Self::transaction_mut, but always commits the transaction.

The only exception is that if the closure panics, a rollback is performed.

pub fn rusqlite_connection(&self) -> Connection

Create a new rusqlite::Connection to the database.

You can do (almost) anything you want with this connection as it is almost completely isolated from all other rust_query connections. The only thing you should not do here is changing the schema. Schema changes are detected with the schema_version pragma and will result in a panic when creating a new rust_query transaction.

The foreign_keys pragma is always enabled here, even if [crate::migrate::ForeignKeys::SQLite] is not used.

Note that many systems have a limit on the number of file descriptors that can exist in a single process. On my machine the soft limit is (1024) by default. If this limit is reached, it may cause a panic in this method.