Struct Db 

pub struct Db { /* private fields */ }

The certified arcature-db engine, re-exported so downstream code targets the Arcature-pinned types through this crate. Db is the explicit ownership handle every API in this crate borrows. The Arcature database handle: one PostgreSQL connection pool with two first-class data paths.

Db holds exactly one sqlx::PgPool and derives the SeaORM DatabaseConnection over the same pool via SqlxPostgresConnector::from_sqlx_postgres_pool. There is never a second pool (Phase 4 spec §4).

Db is Clone + Send + Sync + 'static so it works as normal Axum state (Phase 4 spec §8):

#[derive(Clone)]
struct AppState { db: Db }

There is no DbExtractor, service container, database registry, global singleton, TypeId/Any map, thread-local, or task-local (Phase 4 spec §8, §20). Use Db::sqlx for raw SQL access and Db::orm for SeaORM access — both over the same pool.

Implementations

impl Db

pub async fn close(self)

Close the one connection pool.

This closes the underlying PgPool. All cloned Db handles share the same pool (it is Arc-backed internally), so closing from one handle closes the pool for all handles (Phase 4 spec §29). The SeaORM DatabaseConnection is also closed because it operates over the same pool.

After close, Db::ping returns DbHealthError::Closed and queries fail with a pool-closed error.

impl Db

pub async fn connect(config: DbConfig) -> Result<Db, DbConnectError>

Connect to PostgreSQL using resolved configuration.

Validates the configuration (min > max, zero durations) before any expensive async work runs (Phase 4 spec §19), then builds one PgPool and derives the SeaORM DatabaseConnection over it.

Errors

Returns DbConnectError::Config if the configuration is internally inconsistent, or DbConnectError::Pool if the pool cannot be established (network, auth, server unavailable).

pub fn from_pool(pool: Pool<Postgres>) -> Db

Construct a Db from an existing PgPool.

This is the database escape hatch (Phase 4 spec §9): an expert can build and configure the pool themselves, then hand it to Arcature. The SeaORM connection is derived over the same pool — no second pool is created.

impl Db

pub fn orm(&self) -> &DatabaseConnection

Get the underlying SeaORM DatabaseConnection for ORM access.

This is the first-class SeaORM path (Phase 4 spec §5). The connection is derived over the same PgPool — there is no second pool.

SeaORM entities are application-defined (annotated with #[derive(sea_orm::DeriveEntityModel)]), so this example is ignored here. See examples/basic_query.rs for a runnable program using the SQLx path; the SeaORM path follows the same one-pool structure:

let users = user::Entity::find()
    .filter(user::Column::Active.eq(true))
    .all(db.orm())
    .await?;

impl Db

pub async fn ping(&self) -> Result<(), DbHealthError>

Check database liveness by executing SELECT 1.

Uses the configured pool acquire timeout; it does not hide a 30-second timeout (Phase 4 spec §28). A closed pool returns DbHealthError::Closed. The ping error preserves the upstream sqlx::Error for source chaining. Credentials are never included in the failure (Phase 4 spec §28).

impl Db

pub fn sqlx(&self) -> &Pool<Postgres>

Get the underlying sqlx::PgPool for raw SQLx access.

This is the first-class SQLx escape hatch (Phase 4 spec §5). Use it with sqlx::query! / sqlx::query_as! for compile-time checked SQL, or with the runtime sqlx::query_as for dynamically-built queries:

use arcature_db::sqlx;

#[derive(sqlx::FromRow)]
struct UserRow { id: i32, email: String }

let row = sqlx::query_as::<_, UserRow>("SELECT id, email FROM users WHERE id = $1")
    .bind(42)
    .fetch_one(db.sqlx())
    .await?;

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.