Struct Database 

pub struct Database { /* private fields */ }

A handle to a database.

Examples

use tork_orm_core::Database;

let db = Database::connect("sqlite://app.db", 4).await?;
db.execute("CREATE TABLE t (id INTEGER PRIMARY KEY)".into(), vec![]).await?;

Implementations

impl Database

pub async fn connect(url: &str, max_connections: u32) -> Result<Self>

Connects to a database described by url, with up to max_connections concurrent connections.

The backend is chosen from the URL scheme: sqlite://... (a bare path or :memory:) for SQLite, or postgres://... for PostgreSQL when the postgres feature is enabled.

Errors

Returns an error if the URL names an unsupported backend or the pool cannot be created.

pub fn dialect(&self) -> &Arc<dyn Dialect>

Returns the dialect this database renders queries with.

pub async fn fetch_all( &self, sql: String, params: Vec<Value>, ) -> Result<Vec<Row>>

Runs a row-returning query with bound parameters.

pub async fn execute( &self, sql: String, params: Vec<Value>, ) -> Result<ExecuteResult>

Runs a statement that returns no rows.

pub async fn execute_batch(&self, sql: String) -> Result<()>

Runs a batch of semicolon-separated statements with no bound parameters.

pub fn statement_count(&self) -> u64

Returns the number of statements run through this database so far.

Useful in tests to confirm a query strategy (such as preloading adding one query per relation, not one per row).

pub async fn close(&self)

Releases idle connections held by the pool.

impl Database

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

where F: for<'a> FnOnce(&'a Transaction) -> BoxFuture<'a, Result<R>>, R: Send + 'static,

Runs f inside a transaction, committing on Ok and rolling back on Err.

This is the preferred way to run transactional work. The closure receives a &Transaction that implements Executor, so every ORM method works against it without modification.

The future must be boxed because the compiler cannot name the return type of an async closure; use Box::pin or the transaction! macro from the tork-orm facade, which adds that boilerplate automatically.

Examples

use tork_orm_core::{Database, Executor};

let db = Database::connect("sqlite::memory:", 1).await?;
db.execute("CREATE TABLE t (x INTEGER)".into(), vec![]).await?;
db.transaction(|tx| Box::pin(async move {
    tx.execute("INSERT INTO t VALUES (1)".into(), vec![]).await?;
    tx.execute("INSERT INTO t VALUES (2)".into(), vec![]).await?;
    Ok(())
})).await?;

Errors

Returns an error if BEGIN, any statement inside f, or COMMIT fails.

pub async fn transaction_retry<F, R>( &self, max_attempts: u32, f: F, ) -> Result<R>

where F: for<'a> Fn(&'a Transaction) -> BoxFuture<'a, Result<R>>, R: Send + 'static,

Runs f inside a transaction, retrying up to max_attempts times when it fails with a transient conflict — a lock timeout, deadlock, or serialization failure (see OrmError::is_retryable).

Under serializable isolation or heavy write contention the database may abort a transaction and expect the client to retry. f may run more than once, so it must be safe to re-run (idempotent in its in-memory effects).

Examples

use tork_orm_core::{Database, Executor};

let db = Database::connect("sqlite::memory:", 1).await?;
db.transaction_retry(5, |tx| Box::pin(async move {
    tx.execute("UPDATE accounts SET balance = balance - 10 WHERE id = 1".into(), vec![]).await?;
    Ok(())
})).await?;

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

Opens a new transaction on a pinned connection.

Runs BEGIN on the connection and returns a Transaction handle. The handle implements Executor, so it can be passed directly to ORM query methods. Call Transaction::commit to persist the work, or let the handle drop to roll back automatically.

Errors

Returns an error if the pool has no connections available or BEGIN fails.

Examples

use tork_orm_core::Database;

let db = Database::connect("sqlite::memory:", 1).await?;
let mut tx = db.begin().await?;
db.execute("CREATE TABLE t (x INTEGER)".into(), vec![]).await?;
tx.commit().await?;

pub fn transaction_with(&self) -> TransactionBuilder<'_>

Returns a TransactionBuilder for opening a transaction with a specific isolation level.

Examples

use tork_orm_core::{Database, Executor};

let db = Database::connect("sqlite::memory:", 1).await?;
db.execute("CREATE TABLE t (x INTEGER)".into(), vec![]).await?;
db.transaction_with()
    .immediate()
    .run(|tx| Box::pin(async move {
        tx.execute("INSERT INTO t VALUES (1)".into(), vec![]).await?;
        Ok(())
    }))
    .await?;

Trait Implementations

impl Clone for Database

fn clone(&self) -> Database

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Executor for Database

fn dialect(&self) -> &dyn Dialect

Returns the dialect SQL should be rendered with before running.

fn fetch_all( &self, sql: String, params: Vec<Value>, ) -> impl Future<Output = Result<Vec<Row>>> + Send

Runs a row-returning query.

fn execute( &self, sql: String, params: Vec<Value>, ) -> impl Future<Output = Result<ExecuteResult>> + Send

Runs a statement that returns no rows.