Struct Db 

pub struct Db { /* private fields */ }

Handle to a database: a pool, or an open transaction.

Implementations

impl Db

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

where F: FnOnce(Db) -> Fut, Fut: Future<Output = Result<T, E>>, E: From<OrmError>,

Run f in a transaction, or a savepoint inside a transaction.

Cancelling a closure, child scope or statement makes the transaction unusable. An outer success then fails and rolls back. Concurrent statements and sibling scopes are rejected; recursive nesting through the child is supported. Use the child handle while its scope is active. Escaped handles cannot execute after their scope finishes. Cancellation during COMMIT can leave the server outcome unknown; callers must not retry blindly.

Args: f: Closure receiving the scoped transaction handle.

Returns: The closure result after commit or confirmed savepoint release.

Errors

Closure, backend, capability, busy-scope or aborted-transaction errors.

pub async fn transaction_with<F, Fut, T, E>( &self, isolation: IsolationLevel, f: F, ) -> Result<T, E>

where F: FnOnce(Db) -> Fut, Fut: Future<Output = Result<T, E>>, E: From<OrmError>,

Run a scoped transaction at an explicit isolation level.

Args: isolation: A level supported by the backend; disallowed in nesting. f: Closure receiving the scoped transaction handle.

Returns: The closure result after successful commit.

Errors

As transaction, plus unsupported isolation.

pub async fn schema_change<F, Fut, T, E>( &self, transactional: bool, f: F, ) -> Result<T, E>

where F: FnOnce(Db) -> Fut, Fut: Future<Output = Result<T, E>>, E: From<OrmError>,

Run f on a dedicated schema connection, optionally transactional.

SQLite disables foreign keys before BEGIN and restores them afterwards. A cancelled nested scope makes the connection unusable; it cannot be committed through an escaped handle.

Args: transactional: Whether to wrap schema work in a transaction. f: Closure receiving the dedicated connection handle.

Returns: The closure result after the backend finishes schema work.

Errors

Closure/backend errors; SQLite rejects an already-scoped connection.

pub fn on_commit(&self, hook: impl FnOnce() + Send + 'static)

Register work after the outermost transaction successfully commits.

Hooks of failed or abandoned scopes are discarded. Registration on closed, aborted or temporarily inactive handles is discarded as well. Outside a transaction the callback runs immediately.

Args: hook: Callback invoked after commit.

Returns: None.

impl Db

pub fn new(backend: impl Backend) -> Self

Wrap a backend (connection pool).

pub fn from_arc(backend: Arc<dyn Backend>) -> Self

Wrap a shared backend.

pub fn with_signals(self, signals: Signals) -> Self

Attach the Signals registry model operations dispatch to.

The registry is shared by clones of this handle and by the transaction handles opened from it.

pub fn signals(&self) -> &Signals

The signal registry of this handle.

pub fn same_database(&self, other: &Db) -> bool

Whether self and other talk to the same database: two handles of one pool, or a transaction and the pool it was opened on.

pub fn capabilities(&self) -> BackendCapabilities

Declared capabilities of the underlying backend.

pub fn read_parameter_count( &self, plan: &QueryPlan, ) -> Result<Option<usize>, OrmError>

Count read-plan binds through the backend compiler without I/O.

Args: plan: Complete target read plan, including existing filters.

Returns: Exact count when supported; None for non-reporting backends.

Errors

Foreign database origin, invalid plan or unsupported capability.

pub fn in_transaction(&self) -> bool

Whether this handle runs inside a transaction.

pub fn is_scoped(&self) -> bool

Whether this handle owns a connection or transaction scope.

Returns: True for scoped handles; false for a pool handle.

pub async fn fetch(&self, plan: &QueryPlan) -> Result<QueryResult, OrmError>

Execute a read plan.

Errors

Capability, backend or decode errors.

pub async fn execute(&self, plan: &WritePlan) -> Result<ExecResult, OrmError>

Execute a write plan.

Errors

Capability or backend errors.

pub async fn raw_sql( &self, sql: &str, params: Vec<Value>, ) -> Result<QueryResult, OrmError>

Raw SQL returning rows (db.raw_sql("SELECT .. WHERE id = ?", params![id])).

Placeholders follow the backend (? on SQLite, $1 on PostgreSQL). Parameters are always bound; never format untrusted input into sql.

Errors

Backend errors.

pub async fn raw_execute( &self, sql: &str, params: Vec<Value>, ) -> Result<u64, OrmError>

Raw SQL returning the affected-row count. Parameters are bound.

Errors

Backend errors.

pub async fn execute_script(&self, sql: &str) -> Result<(), OrmError>

Run a parameterless multi-statement script (DDL).

Errors

Backend errors.

impl Db

pub fn objects<M: Model>(&self) -> QuerySet<M>

Queryset over M on this handle (same as M::objects(&db)).

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.