Trait PoolProvider

Source

pub trait PoolProvider:
    Clone
    + Send
    + Sync
    + 'static {
    // Required methods
    fn read(&self) -> &Pool<Postgres>;
    fn write(&self) -> &Pool<Postgres>;
}

Expand description

Trait for providing database pools with read/write routing.

Implementations can provide separate read and write pools for load distribution, or use a single pool for both operations.

§Thread Safety

Implementations must be Clone, Send, and Sync to work with async Rust and be shared across tasks.

§When to Use Each Method

§`.read()` - For Read Operations

Use for queries that:

Don’t modify data (SELECT without FOR UPDATE)
Can tolerate slight staleness (eventual consistency)
Benefit from load distribution

Examples: user listings, analytics, dashboards, search

§`.write()` - For Write Operations

Use for operations that:

Modify data (INSERT, UPDATE, DELETE)
Require transactions
Need locking reads (SELECT FOR UPDATE)
Require read-after-write consistency

Examples: creating records, updates, deletes, transactions

§Example Implementation

use sqlx::PgPool;
use sqlx_pool_router::PoolProvider;

#[derive(Clone)]
struct MyPools {
    primary: PgPool,
    replica: Option<PgPool>,
}

impl PoolProvider for MyPools {
    fn read(&self) -> &PgPool {
        self.replica.as_ref().unwrap_or(&self.primary)
    }

    fn write(&self) -> &PgPool {
        &self.primary
    }
}

Required Methods§

Source

fn read(&self) -> &Pool<Postgres>

Get a pool for read operations.

May return a read replica for load distribution, or fall back to the primary pool if no replica is configured.

Source

fn write(&self) -> &Pool<Postgres>

Get a pool for write operations.

Should always return the primary pool to ensure ACID guarantees and read-after-write consistency.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types§

Source §

impl PoolProvider for Pool<Postgres>

Implement PoolProvider for PgPool for backward compatibility.

This allows existing code using PgPool directly to work with generic code that accepts impl PoolProvider without any changes.

§Example

use sqlx::PgPool;
use sqlx_pool_router::PoolProvider;

async fn query_user<P: PoolProvider>(pools: &P, id: i64) -> Result<String, sqlx::Error> {
    sqlx::query_scalar("SELECT name FROM users WHERE id = $1")
        .bind(id)
        .fetch_one(pools.read())
        .await
}

let pool = PgPool::connect("postgresql://localhost/db").await?;

// Works with PgPool directly
let name = query_user(&pool, 1).await?;