Struct Db 

pub struct Db { /* private fields */ }

Database handle for secure operations.

Security

This type is Clone to support ergonomic sharing in runtimes and service containers. Transaction-bypass is still prevented by the task-local guard: any attempt to call conn() inside a transaction closure fails with DbError::ConnRequestedInsideTx.

Services and repositories must NOT store this type. They should receive &impl DBRunner as a parameter to all methods that need database access.

Usage

// At the entrypoint (handler/command)
let db: Db = ctx.db()?;

// Pass runner to service methods
let conn = db.conn()?;
let result = service.do_something(&conn, &scope).await?;

// Or use a transaction
let (db, result) = db.transaction(|tx| {
    Box::pin(async move {
        service.do_something(tx, &scope).await
    })
}).await;

Implementations

impl Db

pub fn conn(&self) -> Result<DbConn<'_>, DbError>

Get a reference to the underlying DbHandle.

Security

This is pub(crate) to allow internal infrastructure access (migrations, etc.) but prevents service code from extracting the handle. Create a non-transactional database runner.

The returned DbConn borrows from self, ensuring that while a DbConn exists, the Db cannot be used for other purposes (like starting a transaction).

Errors

Returns DbError::ConnRequestedInsideTx if called from within a transaction closure. This prevents the transaction bypass vulnerability where code could create a non-transactional runner that persists writes outside the transaction.

Example

let db: Db = ctx.db()?;
let conn = db.conn()?;

// Use conn for queries
let users = Entity::find()
    .secure()
    .scope_with(&scope)
    .all(&conn)
    .await?;

The Result itself is #[must_use]; this method does not add an extra must-use marker to avoid clippy double_must_use.

pub async fn lock(&self, module: &str, key: &str) -> Result<DbLockGuard>

Acquire an advisory lock with the given key and module namespace.

Errors

Returns an error if the lock cannot be acquired.

pub async fn try_lock( &self, module: &str, key: &str, config: LockConfig, ) -> Result<Option<DbLockGuard>>

Try to acquire an advisory lock with configurable retry/backoff policy.

Errors

Returns an error if an unrecoverable lock error occurs.

pub async fn transaction_ref<F, T>(&self, f: F) -> Result<T, DbError>

where F: for<'a> FnOnce(&'a DbTx<'a>) -> Pin<Box<dyn Future<Output = Result<T, DbError>> + Send + 'a>> + Send, T: Send + 'static,

Execute a closure inside a database transaction (borrowed form).

This variant keeps the call site ergonomic for service containers that store a reusable DB entrypoint (e.g. DBProvider) without exposing DbHandle.

Security

The task-local guard is still enforced: any call to Db::conn() within the closure will fail with DbError::ConnRequestedInsideTx.

Errors

Returns DbError if:

• starting the transaction fails
• the closure returns an error
• commit fails (rollback is attempted on closure error)

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

where E: From<DbError> + Send + 'static, F: for<'a> FnOnce(&'a DbTx<'a>) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>> + Send, T: Send + 'static,

Execute a closure inside a database transaction, mapping infrastructure errors into E.

This is the preferred building block for service-facing entrypoints (like DBProvider) that must return domain errors while still acquiring connections internally.

• The transaction closure returns Result<T, E> (domain error).
• Begin/commit failures are DbError and are mapped via E: From<DbError>.

Security

The task-local guard is enforced for the duration of the closure.

Errors

Returns E if:

• starting the transaction fails (mapped from DbError)
• the closure returns an error
• commit fails (mapped from DbError)

pub async fn transaction<F, T>(self, f: F) -> (Self, Result<T>)

where F: for<'a> FnOnce(&'a DbTx<'a>) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'a>> + Send, T: Send + 'static,

Execute a closure inside a database transaction.

Security

This method consumes self and returns it after the transaction completes. This is critical for security: inside the closure, the original Db is not accessible, so code cannot call db.conn() to create a non-transactional runner.

Additionally, a task-local guard is set during the transaction, so any call to conn() on any Db instance will fail with DbError::ConnRequestedInsideTx.

Example

let db: Db = ctx.db()?;

let (db, result) = db.transaction(|tx| {
    Box::pin(async move {
        // Only `tx` is available here
        service.create_user(tx, &scope, data).await?;
        Ok(user_id)
    })
}).await;

let user_id = result?;

Returns

Returns (Self, Result<T>) where:

• Self is always returned (even on error) so the connection can be reused
• Result<T> contains the transaction result or error

pub async fn in_transaction<T, E, F>( self, f: F, ) -> (Self, Result<T, TxError<E>>)

where T: Send + 'static, E: Debug + Display + Send + 'static, F: for<'a> FnOnce(&'a DbTx<'a>) -> Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>> + Send,

Execute a transaction with typed domain errors.

This variant separates infrastructure errors (connection issues, commit failures) from domain errors returned by the closure.

Example

let (db, result) = db.in_transaction(|tx| {
    Box::pin(async move {
        service.create_user(tx, &scope, data).await
    })
}).await;

match result {
    Ok(user) => println!("Created: {:?}", user),
    Err(TxError::Domain(e)) => println!("Business error: {}", e),
    Err(TxError::Infra(e)) => println!("DB error: {}", e),
}

pub async fn transaction_with_config<T, F>( self, config: TxConfig, f: F, ) -> (Self, Result<T>)

where T: Send + 'static, F: for<'a> FnOnce(&'a DbTx<'a>) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'a>> + Send,

Execute a transaction with custom configuration (isolation level, access mode).

Example

use modkit_db::secure::{TxConfig, TxIsolationLevel};

let config = TxConfig {
    isolation: Some(TxIsolationLevel::Serializable),
    access_mode: None,
};

let (db, result) = db.transaction_with_config(config, |tx| {
    Box::pin(async move {
        // Serializable isolation
        service.reconcile(tx, &scope).await
    })
}).await;

pub fn db_engine(&self) -> &'static str

Return database engine identifier for logging/tracing.

Trait Implementations

impl Clone for Db

fn clone(&self) -> Db

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.