QAIL Zig Documentation

Pure Zig PostgreSQL wire-protocol driver with AST-native query building and PostgreSQL-path parity tracking against qail.rs.

QAIL Zig is the active pure-Zig implementation of the QAIL PostgreSQL stack. It shares the same AST direction as qail.rs, but keeps the runtime, protocol path, and tooling in Zig. Full qail.rs ecosystem parity is still incomplete outside the PostgreSQL-focused track.

Latest Updates (March 2026)

• qail-zig is active again and no longer documented as deferred.
• PG driver hardening now includes AST sanitization, stricter startup/auth sequencing, COPY fail-closed checks, and replication hardening suites.
• Three-way benchmark harnesses now compare pgx, qail.rs, and qail-zig directly.
• qail-zig now has its own versioned changelog and docs track.

What QAIL Zig Covers

Implementation Positioning

• qail.rs is still the production reference and widest implementation.
• qail-zig is the serious pure-Zig track, with active parity work and dedicated benchmarks.
• Security boundary: on the AST flow, the goal remains no application SQL string interpolation surface.

Docs Map

• Start with Installation and Quick Start.
• Use PostgreSQL Driver for transport and feature coverage.
• Use Security Hardening for the recent fail-closed work.
• Use Throughput Benchmarks and qail.rs Parity Status to track the implementation line.

Installation

Requirements

• Zig 0.15+
• PostgreSQL 14+
• macOS, Linux, or another platform supported by the Zig toolchain

Clone and Build

git clone https://github.com/qail-io/qail-zig.git
cd qail-zig
zig build -Doptimize=ReleaseFast

Current macOS Note

On the current macOS 26 host used during parity work, zig build can fail while linking the build runner for the host target. Direct Zig commands work when the target is clamped to an older SDK floor.

Example:

zig test src/lib.zig -target aarch64-macos.15.0 -fno-emit-bin
zig build-exe src/qail_pgx_modes_once.zig -target aarch64-macos.15.0 -O ReleaseFast

This is an environment/toolchain issue, not a qail-zig protocol issue.

Docs Build

The Zig docs book is configured to publish into the existing dev.qail.io tree at public/zig/docs.

cd docs
mdbook build

Quick Start

const std = @import("std");
const qail = @import("qail");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    var driver = try qail.PgDriver.connect(allocator, "127.0.0.1", 5432, "postgres", "mydb");
    defer driver.deinit();

    const cmd = qail.QailCmd.get("users")
        .select(&.{ qail.Expr.col("id"), qail.Expr.col("email") })
        .where(&.{.{ .condition = .{ .column = "active", .op = .eq, .value = .{ .bool = true } } }})
        .limit(10);

    const rows = try driver.fetchAll(&cmd);
    defer {
        for (rows) |*row| row.deinit();
        allocator.free(rows);
    }
}

High-Level Entry Points

• qail.PgDriver.connect(...)
• qail.driver.PgPool.init(...)
• qail.driver.Pipeline.init(...)
• qail.validateAst(...)

Practical Direction

• Use PgDriver for direct command execution and AST-native reads/writes.
• Use Pipeline for high-throughput prepared batches.
• Use PgPool for concurrent prepared singles and scoped workloads.
• Validate untrusted AST input with qail.validateAst before execution.

PostgreSQL Driver

QAIL Zig implements PostgreSQL directly over the wire protocol. The active surface includes:

• plain TCP connections
• connection timeouts
• TLS transport
• startup/auth handling for cleartext, MD5, SCRAM, and enterprise auth hooks
• prepared statement execution
• pipeline execution
• connection pooling
• COPY helpers
• LISTEN / NOTIFY
• logical replication core
• RLS helper APIs

Primary Types

• qail.PgDriver
• qail.driver.Connection
• qail.driver.Pipeline
• qail.driver.PgPool

Driver Direction

The focus of qail-zig is not a SQL-string convenience wrapper. The serious path is:

1. build AST or validated command input
2. encode PostgreSQL protocol frames directly
3. execute over a pure-Zig transport path
4. fail closed on protocol and state-machine violations

Current Emphasis

Recent work concentrated on hardening the PG driver instead of broadening surface area first. That includes startup/auth state validation, protocol framing checks, COPY sequencing checks, replication stream fail-closed handling, and AST sanitization.

Pool, Pipeline, and COPY

Pool

PgPool provides fixed-size connection pooling with scoped helpers and reset-on-release behavior.

Use it when:

• you want concurrent prepared single-query workloads
• you need pooled RLS or tenant-scoped acquisition
• you want explicit min_connections / max_connections

Pipeline

Pipeline batches Bind + Execute messages and sends one Sync per batch. This is the highest-throughput path for prepared count-only or row-collecting workloads on a single connection.

Use it when:

• you already have a prepared statement
• batch throughput matters more than per-query latency
• you want one connection and many completions per round trip

COPY

The COPY helpers are active and hardened.

Supported areas:

• COPY FROM STDIN helpers
• COPY TO STDOUT raw export helpers
• stricter protocol sequencing checks
• fail-closed handling on malformed COPY states and oversized data

COPY is now treated as a protocol feature that must reject unexpected backend frames rather than attempting to continue.

Security Hardening

The recent qail-zig work focused on PG-driver hardening parity against qail.rs.

Added or Tightened

• AST sanitization for untrusted command input
• raw SQL escape-hatch rejection on the sanitization path
• stricter startup/auth ordering checks
• authentication method-switch rejection
• SASL final / AuthenticationOk sequencing checks
• Bind / Parse parameter-count guards
• COPY fail-closed state validation
• replication stream fail-closed handling on malformed CopyData
• startup, protocol, and replication hardening suites

Why This Matters

Protocol bugs are often state-machine bugs, not just parsing bugs. The hardening work in qail-zig now rejects malformed or unexpected backend sequences earlier instead of silently progressing through them.

Current Safety Model

• AST-native execution is the preferred path.
• validateAst exists for untrusted or deserialized command ingress.
• protocol handlers are moving toward explicit state validation and drain-to-ready behavior after errors.

Remaining Direction

The active parity target is not “support every surface first”. It is “close driver and hardening gaps without weakening the transport guarantees.”

Throughput Benchmarks

The current benchmark story for qail-zig is based on direct three-way comparisons between:

• pgx (Go)
• qail.rs (Rust)
• qail-zig

Harness

The active harness uses matching one-shot runners for:

• single — prepared single-query path on one connection
• pipeline — prepared batch pipeline on one connection
• pool10 — prepared singles over ten connections

Latest Isolated 12-Sample Medians

Reading the Results

• Zig currently leads on single and pool10 in this harness.
• Rust still leads on pipeline.
• pool10 is the noisiest mode and should always be read with variance, not just peak numbers.

Benchmark Discipline

The benchmark numbers are only meaningful when the compared paths are equivalent. The current work explicitly separated:

• interleaved round-robin runs
• isolated block runs
• per-round CSV/SVG graph output

That makes it easier to see whether a result comes from the implementation path or from order effects.

qail.rs Parity Status

qail-zig tracks qail.rs as the reference implementation for PostgreSQL driver behavior and hardening.

Current Snapshot

As of 2026-03-28, the narrow AST/codegen parity checks against /Users/orion/qail.rs are green:

• ./scripts/check_codegen_sync.sh /Users/orion/qail.rs -> codegen sync check passed
• ./scripts/check_parity.sh /Users/orion/qail.rs -> AST actions: rust=75 zig=76, Encoder actions: rust=57 zig=76, parity check passed

That means the Rust-driven AST porting/codegen path is working for its current scope, and the PostgreSQL AST encoder still covers the Rust action surface completely.

Active Areas with Strong Coverage

• AST core exports
• Rust-driven AST codegen sync
• PostgreSQL wire protocol
• prepared execution and pipelines
• pooling
• TLS transport
• COPY in/out helpers
• LISTEN / NOTIFY
• logical replication core
• RLS helper APIs
• startup/auth policy controls
• protocol hardening suites

Current Reality

Parity is not complete across the entire qail.rs ecosystem. The largest gaps remain outside the core PG driver track:

• gateway / auto-REST / WebSocket / OpenAPI stack
• qdrant vector driver and hybrid execution path
• workflow engine
• typed schema codegen (qail types) and build-time SQL / N+1 guard rails
• some CLI breadth (qail init, exec, types, vector/hybrid flows)
• some LSP breadth (notably formatting and code actions)
• direct SDKs and broader non-driver surfaces

Important Policy Delta

There is still one meaningful runtime policy difference between the repos:

• qail.rs removed raw runtime SQL APIs from the normal execution path.
• qail-zig still carries .raw in the AST for trusted/local use.
• Current mitigation: validateAst rejects .raw and other procedural escape hatches for untrusted or deserialized AST ingress.

PG Driver Focus

The PG driver is the serious parity target right now. That is why recent work landed in:

• sanitization
• startup/auth sequencing
• protocol hardening
• replication hardening
• benchmark comparability

For detailed driver parity notes, see the repository parity file:

• PARITY_AST_PG_DRIVER.md

API Surface

The high-signal public surface for qail-zig currently centers on the PostgreSQL driver and related tooling.

Core Exports

• qail.PgDriver
• qail.QailCmd
• qail.Expr
• qail.validateAst

Driver Module

• qail.driver.Connection
• qail.driver.Pipeline
• qail.driver.PgPool
• qail.driver.TlsConnection
• qail.driver.ConnectOptions
• qail.driver.AuthOptions
• qail.driver.RlsContext

Tooling

• CLI entry via zig build cli
• LSP server via zig build / qail-lsp
• benchmark runners under src/*bench*.zig

Recommended Reading Order

• Start with the driver docs.
• Then read the hardening page.
• Then use the parity page to understand what is intentionally in-scope versus still missing.

Changelog

QAIL Zig now tracks its own release notes separately from qail.rs.

Current Highlights (v0.6.0)

• PG-driver hardening was expanded with AST sanitization, startup/auth sequencing checks, COPY fail-closed behavior, and replication hardening tests.
• Three-way benchmark harnesses now compare pgx, qail.rs, and qail-zig directly.
• qail-zig docs and changelog now have their own track instead of being implied through qail.rs.
• The project is documented as active again rather than deferred.

For the repository changelog, see:

• CHANGELOG.md