Struct Db 

pub struct Db { /* private fields */ }

The database pool. Take it in a handler with State(db): State<Db>.

Models, queries and sql() take &db (or &mut tx inside a Transaction). For something only sqlx can do, reach the underlying pool with Db::sqlite or Db::postgres (with the postgres feature).

Implementations

impl Db

pub fn dialect(&self) -> Dialect

The engine this pool talks to.

pub fn sqlite(&self) -> Option<&SqlitePool>

The sqlx pool, when the database is SQLite.

pub fn postgres(&self) -> Option<&PgPool>

The sqlx pool, when the database is PostgreSQL.

pub async fn begin(&self) -> Result<Transaction, DbError>

Starts a transaction. Pass &mut tx wherever a &db goes, then tx.commit(); dropping it without committing rolls it back.

pub async fn transaction<T, F>(&self, work: F) -> Result<T>

where F: for<'t> FnMut(&'t mut Transaction) -> BoxFuture<'t, Result<T>>,

Runs work in a transaction: committed when it returns Ok, rolled back when it returns Err.

let moved = db
    .transaction_retrying(3, |tx| {
        Box::pin(async move {
            renox::db::sql("UPDATE accounts SET balance = balance - 100 WHERE id = 1")
                .execute(&mut *tx)
                .await?;
            renox::db::sql("UPDATE accounts SET balance = balance + 100 WHERE id = 2")
                .execute(&mut *tx)
                .await?;
            Ok(100)
        })
    })
    .await?;

pub async fn transaction_retrying<T, F>( &self, attempts: u32, work: F, ) -> Result<T>

where F: for<'t> FnMut(&'t mut Transaction) -> BoxFuture<'t, Result<T>>,

Like Db::transaction, trying up to attempts times when another transaction got in the way (SQLite busy, PostgreSQL serialization failure or deadlock), with a short, growing pause in between. work must be safe to run again.

pub fn retrying<'a, T, F, Fut>( &'a self, attempts: u32, work: F, ) -> impl Future<Output = Result<T>> + Send + 'a

where T: Send + 'a, F: FnMut() -> Fut + Send + 'a, Fut: Future<Output = Result<T>> + Send + 'a,

Runs work again (up to attempts times, with a short, growing pause) while it fails because another transaction got in the way (SQLite busy, PostgreSQL serialization failure or deadlock). work opens and commits its own transaction, so unlike Db::transaction_retrying it can borrow from the caller, and it can roll back and still return a value (drop or rollback the transaction instead of committing).

enum Transfer { Done, Short }

let outcome = db
    .retrying(3, || async {
        let mut tx = db.begin().await?;
        let taken = renox::db::sql(
            "UPDATE accounts SET balance = balance - ? WHERE id = ? AND balance >= ?",
        )
        .bind(amount) // borrowed from the caller
        .bind(from)
        .bind(amount)
        .execute(&mut tx)
        .await?;
        if taken == 0 {
            tx.rollback().await?;
            return Ok(Transfer::Short); // rolled back, with an answer
        }
        renox::db::sql("UPDATE accounts SET balance = balance + ? WHERE id = ?")
            .bind(amount)
            .bind(to)
            .execute(&mut tx)
            .await?;
        tx.commit().await?;
        Ok(Transfer::Done)
    })
    .await?;

pub async fn begin_immediate(&self) -> Result<Transaction, DbError>

A transaction that takes SQLite’s write lock at once (BEGIN IMMEDIATE), so what it reads can’t change before it writes: the SQLite counterpart of lock_for_update. Same as begin on PostgreSQL.

pub async fn close(&self)

Closes every connection; later queries fail.

Trait Implementations

impl Clone for Db

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Db

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'c> Executor<'c> for &'c Db

impl From<Pool<Postgres>> for Db

Available on crate feature postgres only.

fn from(pool: PgPool) -> Self

Converts to this type from the input type.

impl From<Pool<Sqlite>> for Db

fn from(pool: SqlitePool) -> Self

Converts to this type from the input type.

impl FromRef<AppState> for Db

fn from_ref(state: &AppState) -> Self

Converts to this type from a reference to the input type.