What is qail-zig?

qail-zig is the Zig-first PostgreSQL integration track for QAIL. It provides a native driver, ast-driven query builder surface, and developer toolchain designed specifically for Zig.

Zig-first PostgreSQL runtime

Core driver, pooling, pipelining, TLS, and COPY paths are implemented in Zig; Linux enterprise auth can use optional platform GSSAPI/libc integration.

AST-native query path

Queries are built as typed objects and carried into the PostgreSQL wire protocol path instead of being hand-assembled as strings first.

Tooling included

CLI, migrations, REPL, formatter, schema diff, diagnostics, hover, and completion support all live in the same repo.

Parity-oriented implementation

qail.rs remains the production reference and source of truth; qail-zig tracks it through generated AST types and explicit capability work.

AST-native query example

The goal is not just to expose a low-level PostgreSQL socket. qail-zig gives Zig code a typed query path that stays inside Zig all the way down to driver execution.

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

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    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").limit(10);
    const rows = try driver.fetchAll(&cmd);
    defer allocator.free(rows);
}

Aligned with qail.rs

qail-zig offers a dedicated, heavily-optimized runtime track separate from qail.rs. While it shares the same parity targets, it is built exclusively for Zig developers.

Separate Zig runtime track

qail-zig

Zig-first PostgreSQL driver/runtime
AST builders, parser, CLI, and LSP in Zig
Focused on the PostgreSQL execution path
Public docs and Zig-only changelog under /zig

Reference platform track

qail.rs

Shared-core AST platform and parity target
qail-pg, qdrant, gateway, and policy flow
Multi-entry adapter pipeline and broader runtime surface
Production reference for generated Zig parity types

Implementation Status

qail-zig is production-ready and highly mature. Explore our implementation scope, type-parity discipline, and comprehensive operational surfaces.

Code surface

~45,000 lines

Zig implementation across driver, AST, CLI, LSP, codegen, fuzzing, and benchmark harnesses, with optional Linux GSSAPI/libc enterprise-auth integration.

Generated parity

26 enums + 9 structs

Auto-generated from qail.rs AST sources to keep the Zig type surface aligned.

Builder modules

10 modules

Conditions, aggregates, binary, cast, JSON, literals, time, case/when, shortcuts, and typed helpers.

Area	Status	Notes
Driver core	Live	Wire protocol encode/decode, startup/auth flow, prepared execution, and row decoding are implemented in Zig.
Operational paths	Live	Single connection, pooled connections, prepared pipeline, TLS, and COPY workflows are public.
AST surface	Live	Typed query builders, generated parity types, transpile path, and parser work are part of the Zig repo.
Security hardening	Active	AST sanitization, startup/auth sequencing checks, COPY fail-closed behavior, and replication protocol hardening are called out explicitly.
Developer tooling	Live	CLI, migrations, REPL, formatter, diff, linting, and LSP support ship with the project.
Positioning	Separate track	qail-zig is no longer presented as deferred, but it is also not the same thing as the full qail.rs platform.

Ecosystem Surfaces

Dive right into the resources you need: documentation for setup, release history in the changelog, open source code on GitHub, and a quick start guide.

Canonical docs book

/zig/docs

Installation, quick start, PostgreSQL driver internals, security hardening, parity notes, and API reference.

Current benchmark page

/zig/benchmarks

Current PostgreSQL driver benchmark report for qail-zig versus pg.zig, including the detailed five-workload matrix and methodology.

Zig-only release track

/zig/changelog

Dedicated qail-zig release history so Zig progress does not get buried inside the Rust workspace changelog.

Engineering study

Study: Zig 0.16 std.Io

Deep dive into the Zig 0.16 runtime migration, threaded versus evented selection, and what async means in qail-zig today.

First real query

Quick start

Fastest path from dependency install to a working PgDriver connection and AST-native query in Zig.

Source + releases

GitHub

Source of truth for tags, release assets, project structure, benchmark harnesses, and implementation details.

Install and import

For full setup notes, use the installation guide and quick start in the docs book. The sequence below is the shortest dependency flow for a Zig project.

Step 1: Add the release tarball

Pin the public qail-zig release in build.zig.zon.

.dependencies = .{
    .qail_zig = .{
        .url = "https://github.com/qail-io/qail-zig/archive/refs/tags/v0.8.0.tar.gz",
        .hash = "...", // filled by zig fetch --save
    },
};

Step 2: Fetch and record the hash

Run zig fetch --save once so the dependency hash is stored locally.

zig fetch --save https://github.com/qail-io/qail-zig/archive/refs/tags/v0.8.0.tar.gz

Step 3: Import the module

Bind the dependency and expose it as qail in the root module.

const qail = b.dependency("qail_zig", .{});
exe.root_module.addImport("qail", qail.module("qail"));

Performance Milestones

qail-zig consistently delivers class-leading latency and throughput. Review our transparent benchmark summaries below, or visit the methodology hub for raw tables.

Current public read: in the March 31, 2026 qail-zig versus pg.zig matrix, qail-zig leads 9 of 10 published shared throughput slices across single and pool10 (single aggregate currently favors pg.zig). Pipeline remains a qail-zig-only capability and is intentionally kept off this comparison page so the matrix stays clean. On the v0.8.0 Zig 0.16 branch, pgzig-bench is temporarily disabled until pg.zig's build script is updated, so this page currently tracks the latest published matrix. Full methodology and raw output live at /zig/benchmarks.

Mode	Outcome	Read
Single (shared prepared, 1 conn)	qail-zig leads 4 of 5 slices	March 31, 2026 5-round medians: qail-zig leads point, wide_rows, large_rows, and many_params (49,070 q/s versus 21,597 on point), while pg.zig currently leads single aggregate (291.296 vs 253.936 q/s).
Pool10 (shared prepared, 10 conns)	qail-zig leads	qail-zig leads all five pool10 workloads versus pg.zig in the same 5-round run, peaking at 161,884 q/s on point lookup and 157,960 q/s on many_params.
Pipeline	qail-zig-only capability	Pipeline is intentionally not part of the pg.zig comparison page so the published matrix stays focused on the clearest shared modes.

Historical Zig benchmark page: /benchmarks/zig-50m. Current canonical benchmark index: /benchmarks.

Operational Tips

qail-zig is active, not deferred: driver, pooling, TLS, COPY, CLI, LSP, hardening work, and benchmark harnesses are public.
Start onboarding from /zig/docs, then use /zig for positioning and /zig/changelog for release tracking.
Treat qail.rs as the broader reference platform while using qail-zig as the dedicated Zig-first PostgreSQL runtime track.
Use /zig/benchmarks for full Zig benchmark methodology and /benchmarks for the cross-site benchmark index.

Open Zig Docs Open Zig Changelog View qail-zig on GitHub