Struct PgPool

Source

pub struct PgPool { /* private fields */ }

Expand description

§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§

Source §

impl PgPool

Source

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

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

§Example

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

Source

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

Create a new connection pool.

Source

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.

Source

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::operator("550e8400-e29b-41d4-a716-446655440000")
).await?;
// All queries through `conn` are now scoped to this operator

Source

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.

Source

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_operator_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.

Source

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

Source