wasi-pg-client

A production-grade PostgreSQL client library for WASI Preview 2.

Quick Start

use wasi_pg_client::{Connection, Config};

#[wstd::main]
async fn main() -> Result<(), wasi_pg_client::PgError> {
    let config = Config::from_uri("postgresql://user:pass@localhost/mydb")?;
    let mut conn = Connection::connect(&config).await?;

    let result = conn.query("SELECT id, name FROM users").await?;
    for row in result.iter() {
        let id: i32 = row.get(0)?;
        let name: String = row.get(1)?;
        println!("{}: {}", id, name);
    }

    conn.close().await?;
    Ok(())
}

Key Features

• Full PostgreSQL wire protocol v3 — simple and extended query protocols
• Parameterized queries — SQL injection prevention with $1, $2 syntax
• Prepared statements — with automatic LRU caching
• Streaming results — O(1) memory for large queries via RowStream
• Parameterized streaming — query_params_stream() for streaming with parameters
• Transactions — RAII guards with automatic rollback on drop
• Savepoints — nested transaction scopes
• COPY protocol — bulk import/export with CSV and binary support
• LISTEN/NOTIFY — asynchronous pub/sub with timeout support
• TLS — via rustls (pure Rust, WASI-compatible)
• SCRAM-SHA-256 and MD5 authentication
• Connection pooling — via wasi_pg_client::pool module with Mutex-based thread safety
• Automatic reconnection — with exponential backoff and session state rebuild
• Retry policies — for transient errors (serialization failures, deadlocks)
• Query cancellation — out-of-band via CancelToken (with TLS support)
• Runtime parameter setting — set_param() with automatic re-application on reconnect
• Structured logging — via tracing
• Compiles to wasm32-wasip2 and native targets

Feature Flags

WASI P2 Requirements

This library targets wasm32-wasip2. When running in wasmtime, use:

wasmtime run --wasi inherit-network --wasi inherit-env component.wasm

The getrandom crate must be configured with features = ["wasi"] for cryptographic randomness (required for SCRAM auth and TLS).

Tracing

When the tracing feature is enabled, the library emits structured events at the following levels:

⚠️ TRACE may expose sensitive data. Use only in development, never in production.