Struct PgPool 

pub struct PgPool { /* private fields */ }

Example

let config = PoolConfig::new("localhost", 5432, "user", "db")
    .password("secret")
    .max_connections(20);
let pool = PgPool::connect(config).await?;
// Get a connection from the pool
let mut conn = pool.acquire_raw().await?;
conn.simple_query("SELECT 1").await?;

Implementations

impl PgPool

pub async fn from_config() -> PgResult<Self>

Create a pool from qail.toml (loads and parses automatically).

Example

let pool = PgPool::from_config().await?;

pub async fn connect(config: PoolConfig) -> PgResult<Self>

Create a new connection pool.

pub async fn acquire_raw(&self) -> PgResult<PooledConnection>

Acquire a raw connection from the pool (crate-internal only).

Safety (not unsafe in the Rust sense, but security-critical)

This returns a connection with no RLS context. All tenant data queries on this connection will bypass row-level security.

Safe usage: Pair with fetch_all_with_rls() for pipelined RLS+query execution (single roundtrip). Or use acquire_with_rls() / acquire_with_rls_timeout() for the 2-roundtrip path.

Unsafe usage: Running queries directly on a raw connection without RLS context. Every call site MUST include a // SAFETY: comment explaining why raw acquisition is justified.

pub async fn acquire_with_rls( &self, ctx: RlsContext, ) -> PgResult<PooledConnection>

Acquire a connection with RLS context pre-configured.

Sets PostgreSQL session variables for tenant isolation before returning the connection. When the connection is dropped, it automatically clears the RLS context before returning to the pool.

Example

use qail_core::rls::RlsContext;

let mut conn = pool.acquire_with_rls(
    RlsContext::tenant("550e8400-e29b-41d4-a716-446655440000")
).await?;
// All queries through `conn` are now scoped to this tenant

pub async fn with_rls<T, F>(&self, ctx: RlsContext, f: F) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped connection helper that guarantees release() after closure execution.

Prefer this over manual acquire_with_rls() in normal request handlers.

pub async fn with_system<T, F>(&self, f: F) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped helper for system-level operations (RlsContext::empty()).

pub async fn with_global<T, F>(&self, f: F) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped helper for global/platform row access (tenant_id IS NULL).

pub async fn with_tenant<T, F>(&self, tenant_id: &str, f: F) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped helper for single-tenant access.

pub async fn acquire_with_rls_timeout( &self, ctx: RlsContext, timeout_ms: u32, ) -> PgResult<PooledConnection>

Acquire a connection with RLS context AND statement timeout.

Like acquire_with_rls(), but also sets statement_timeout to prevent runaway queries from holding pool connections indefinitely.

pub async fn with_rls_timeout<T, F>( &self, ctx: RlsContext, timeout_ms: u32, f: F, ) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped connection helper that guarantees release() after closure execution.

pub async fn acquire_with_rls_timeouts( &self, ctx: RlsContext, statement_timeout_ms: u32, lock_timeout_ms: u32, ) -> PgResult<PooledConnection>

Acquire a connection with RLS context, statement timeout, AND lock timeout.

Like acquire_with_rls_timeout(), but also sets lock_timeout to prevent queries from blocking indefinitely on row/table locks. When lock_timeout_ms is 0, the lock_timeout clause is omitted.

pub async fn with_rls_timeouts<T, F>( &self, ctx: RlsContext, statement_timeout_ms: u32, lock_timeout_ms: u32, f: F, ) -> PgResult<T>

where F: for<'a> FnOnce(&'a mut PooledConnection) -> ScopedPoolFuture<'a, T>,

Scoped connection helper that guarantees release() after closure execution.

pub async fn acquire_system(&self) -> PgResult<PooledConnection>

Acquire a connection for system-level operations (no tenant context).

Sets RLS session variables to maximally restrictive values:

• app.current_tenant_id = ''
• app.current_agent_id = ''
• app.is_super_admin = false

Use this for startup introspection, migrations, and health checks that must not operate within any tenant scope.

pub async fn acquire_global(&self) -> PgResult<PooledConnection>

Acquire a connection scoped to global/platform rows.

Shorthand for acquire_with_rls(RlsContext::global()). Use this for shared reference data (for example: currencies, ports, vessel types) stored as tenant_id IS NULL.

pub async fn acquire_for_tenant( &self, tenant_id: &str, ) -> PgResult<PooledConnection>

Acquire a connection scoped to a specific tenant.

Shorthand for acquire_with_rls(RlsContext::tenant(tenant_id)). Use this when you already know the tenant UUID and want a tenant-scoped connection in a single call.

Example

let mut conn = pool.acquire_for_tenant("550e8400-...").await?;
// All queries through `conn` are now scoped to this tenant

pub async fn acquire_with_branch( &self, ctx: &BranchContext, ) -> PgResult<PooledConnection>

Acquire a connection with branch context pre-configured.

Sets PostgreSQL session variable app.branch_id for data virtualization. When the connection is dropped, it automatically clears the branch context.

Example

use qail_core::branch::BranchContext;

let ctx = BranchContext::branch("feature-auth");
let mut conn = pool.acquire_with_branch(&ctx).await?;
// All queries through `conn` are now branch-aware

pub async fn idle_count(&self) -> usize

Get the current number of idle connections.

pub fn active_count(&self) -> usize

Get the number of connections currently in use.

pub fn max_connections(&self) -> usize

Get the maximum number of connections.

pub async fn stats(&self) -> PoolStats

Get comprehensive pool statistics.

pub fn is_closed(&self) -> bool

Check if the pool is closed.

pub async fn close(&self)

Close the pool gracefully.

Rejects new acquires immediately, then waits up to acquire_timeout for in-flight connections to be released before dropping idle connections. Connections released after closure are destroyed by return_connection and not returned to the idle queue.

pub async fn close_graceful(&self, drain_timeout: Duration)

Close the pool gracefully with an explicit drain timeout.

pub async fn maintain(&self)

Run one maintenance cycle: evict stale idle connections and backfill to min_connections. Called periodically by spawn_pool_maintenance.

Trait Implementations

impl Clone for PgPool

fn clone(&self) -> PgPool

Returns a duplicate of the value.

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

Performs copy-assignment from source.