prax-postgres 0.13.2

PostgreSQL driver for the Prax ORM with connection pooling
Documentation

prax-postgres

PostgreSQL query engine for Prax ORM.

Overview

prax-postgres provides an async PostgreSQL backend using tokio-postgres with deadpool-postgres connection pooling.

Features

  • Async query execution with Tokio
  • Connection pooling via deadpool-postgres
  • Transaction support with savepoints
  • Prepared statement caching
  • SSL/TLS support
  • LISTEN / NOTIFY with PgListener (dedicated connection, automatic reconnect with backoff, Lagged / ChannelsDropped events) and PgConnection::notify / PgTransaction::notify
  • Recycling policy via PgRecycling (Fast default, Verified, Clean) and PoolConfig::recycle_timeout; jittered max_lifetime
  • Row locks (FOR UPDATE / FOR SHARE, SKIP LOCKED, NOWAIT) through .lock(RowLock::for_update().skip_locked()) on find_many / find_first / find_unique
  • Typed array and raw bytea parameter binding

Usage

use prax_postgres::{PgConfig, PgEngine, PgPool, PoolConfig, PgRecycling};

let config = PgConfig::from_url("postgresql://user:pass@localhost/db")?;
let pool = PgPool::new(config).await?;
let engine = PgEngine::new(pool);

// Execute queries through the engine with a Prax client
let client = PraxClient::with_engine(engine);
let users = client.user().find_many().exec().await?;

Configuration

PoolConfig is #[non_exhaustive]: start from PoolConfig::default() and assign fields.

use std::time::Duration;

let mut pool_config = PoolConfig::default();
pool_config.max_connections = 20;
pool_config.recycling = PgRecycling::Clean; // reset session state on checkout
pool_config.recycle_timeout = Some(Duration::from_secs(5));
pool_config.max_lifetime = Some(Duration::from_secs(30 * 60));

let pool = PgPool::with_pool_config(config, pool_config).await?;

PgRecycling::Fast (the default) does not reset session state, so SET, SET ROLE, search_path or tenant settings leak to the next checkout; use Clean (or SET LOCAL) with row-level security. max_lifetime and idle_timeout (default 10 minutes, measured from the connection's last checkout) are enforced when a connection is checked out: an expired one is replaced instead of handed out.

Detecting dead connections

By default the driver sends the first TCP keepalive after 2 hours idle and sets no TCP_USER_TIMEOUT, so a connection whose server disappeared without closing it (failover, network black-hole) can hang a query for ~15 minutes or go unnoticed for hours. Bound that with the libpq URL parameters or the matching PgConfig fields / PgConfigBuilder setters:

postgresql://user:pass@host/db?keepalives_idle=30&keepalives_interval=10&keepalives_count=3&tcp_user_timeout=30000
URL parameter PgConfig field Unit
keepalives (0 disables) keepalives: bool -
keepalives_idle keepalives_idle: Option<Duration> seconds
keepalives_interval keepalives_interval: Option<Duration> seconds
keepalives_count (or keepalives_retries) keepalives_retries: Option<u32> probes
tcp_user_timeout (Linux) tcp_user_timeout: Option<Duration> milliseconds

Unset or 0 keeps the driver/OS default. These are client socket settings and are never sent to the server as -c options. Combine them with PgRecycling::Verified (or Clean) so a connection that died while idle is replaced at checkout.

LISTEN / NOTIFY

use prax_postgres::{PgListener, PgListenerEvent};

let mut listener = PgListener::connect(&config).await?;
listener.listen("events").await?;
loop {
    match listener.recv().await? {
        PgListenerEvent::Notification(n) => println!("{}: {}", n.channel, n.payload),
        PgListenerEvent::Disconnected { error, .. } => eprintln!("reconnecting: {error}"),
        PgListenerEvent::Reconnected | PgListenerEvent::Lagged { .. } => { /* resync */ }
        PgListenerEvent::ChannelsDropped { channels, .. } => eprintln!("dropped {channels:?}"),
        _ => {}
    }
}

Send notifications with PgConnection::notify, PgTransaction::notify or PgEngine::notify (inside PraxClient::transaction, tx.engine().notify(..) is delivered only on commit). Connect the listener directly to PostgreSQL, not through a transaction-mode pooler. Any role can NOTIFY any channel: treat payloads as untrusted.

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.