Struct DbHandle 

pub struct DbHandle { /* private fields */ }

Main handle.

Implementations

impl DbHandle

pub fn detect(dsn: &str) -> Result<DbEngine>

Detect engine by DSN.

Note: we only check scheme prefixes and don’t mutate the tail (credentials etc.).

Errors

Returns DbError::UnknownDsn if the DSN scheme is not recognized.

pub async fn connect(dsn: &str, opts: ConnectOpts) -> Result<Self>

Connect and build handle.

Errors

Returns an error if the connection fails or the DSN is invalid.

pub async fn close(self)

Graceful pool close. (Dropping the pool also closes it; this just makes it explicit.)

pub fn engine(&self) -> DbEngine

Get the backend.

pub fn dsn(&self) -> &str

Get the DSN used for this connection.

pub fn sea_secure(&self) -> SecureConn

Create a secure database connection for scoped operations.

Returns a SecureConn wrapper that requires SecurityCtx for each operation. This is the recommended way to access the database from application code.

Example

use modkit_db::secure::{SecurityCtx, AccessScope};

let secure_conn = db_handle.sea_secure();

// Security context from API request
let ctx = SecurityCtx::for_tenants(vec![tenant_id], user_id);

// All queries require context and are automatically scoped
let users = secure_conn.find::<user::Entity>(&ctx)?
    .all(secure_conn.conn())
    .await?;

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 begin(&self) -> Result<DbTransaction<'_>>

Begin a transaction (returns appropriate transaction type based on backend).

Errors

Returns an error if the transaction cannot be started.

Trait Implementations

impl Clone for DbHandle

fn clone(&self) -> DbHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DbHandle

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

Formats the value using the given formatter.