qail-pg

PostgreSQL driver for QAIL - native wire protocol

A high-performance PostgreSQL driver that speaks the wire protocol directly. No SQL strings, no SQL injection - just pure AST-to-wire encoding.

Features

• AST-Native - Compiles QAIL AST directly to PostgreSQL wire protocol
• 28% Faster - Benchmarked at 1.36M rows/s COPY (vs asyncpg at 1.06M rows/s)
• Query Pipelining - 24x faster batch operations via pipeline_batch()
• SSL/TLS - Production-ready with tokio-rustls
• SCRAM-SHA-256 - Secure password authentication
• Connection Pooling - Built-in PgPool
• Transactions - Full begin/commit/rollback support

Installation

[!CAUTION] Alpha Software: QAIL is currently in alpha. While we strive for stability, the API is evolving to ensure it remains ergonomic and truly AST-native. Do not use in production environments yet.

[dependencies]
qail-pg = "0.13.1"
qail-core = "0.13.1"

Quick Start

use qail_core::ast::{QailCmd, builders::*};
use qail_pg::PgDriver;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect with password
    let mut driver = PgDriver::connect_with_password(
        "localhost", 5432, "postgres", "mydb", "password"
    ).await?;

    // Build a query using QAIL AST
    let cmd = QailCmd::get("users")
        .columns([col("id"), col("name"), col("email")])
        .filter(eq("active", true))
        .order_by([("created_at", Desc)])
        .limit(10);

    // Execute and fetch rows
    let rows = driver.fetch_all(&cmd).await?;
    
    for row in rows {
        let name: String = row.get("name");
        println!("User: {}", name);
    }

    Ok(())
}

High-Performance Batch Operations

// Execute 10,000 queries in a single network round-trip
let cmds: Vec<QailCmd> = (0..10_000)
    .map(|i| QailCmd::add("events")
        .columns(["user_id", "event_type"])
        .values([Value::Int(i), Value::String("login".to_string())])
    ).collect();

let count = driver.pipeline_batch(&cmds).await?;
println!("Inserted {} rows", count);

COPY Protocol (Bulk Insert)

use qail_pg::protocol::CopyEncoder;

// Build COPY data
let mut encoder = CopyEncoder::new();
for i in 0..1_000_000 {
    encoder.begin_row();
    encoder.write_i64(i);
    encoder.write_str(&format!("user_{}", i));
    encoder.end_row();
}

// Execute COPY
driver.copy_bulk_bytes("users", &["id", "name"], encoder.finish()).await?;

Connection Pooling

use qail_pg::PgPool;

// Create a pool with 10 connections
let pool = PgPool::new(
    "localhost", 5432, "postgres", "mydb", Some("password"), 10
).await?;

// Acquire a connection
let mut conn = pool.acquire().await?;
let rows = conn.fetch_all(&cmd).await?;

SSL/TLS Support

qail-pg uses tokio-rustls for TLS connections:

// SSL is auto-negotiated during connection
let driver = PgDriver::connect_with_password(
    "pg.example.com", 5432, "user", "db", "pass"
).await?;

Ergonomic Expression Builders

qail-pg works seamlessly with qail-core's ergonomic builders:

use qail_core::ast::builders::*;

// COUNT(*) FILTER (WHERE condition)
count_filter(vec![eq("status", "active")]).alias("active_count")

// NOW() - INTERVAL '24 hours'
now_minus("24 hours")

// CASE WHEN ... ELSE ... END
case_when(gt("score", 80), text("pass"))
    .otherwise(text("fail"))
    .alias("result")

// Type casting
cast(col("amount"), "float8")

Type Support

License

MIT

🤝 Contributing & Support

We welcome issue reports on GitHub! Please provide detailed descriptions to help us reproduce and fix the problem. We aim to address critical issues within 1-5 business days.