What is qail-zig?
qail-zig is the pure Zig PostgreSQL integration track for QAIL. It provides a native driver, ast-driven query builder surface, and developer toolchain designed specifically for Zig.
Pure Zig PostgreSQL runtime
Driver, pooling, pipelining, TLS, and COPY are implemented directly in Zig with no FFI runtime dependency.
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.
qail-zig
- Pure Zig 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
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.
~19,800 lines
Pure Zig across driver, AST, CLI, LSP, codegen, fuzzing, and benchmark harnesses.
26 enums + 9 structs
Auto-generated from qail.rs AST sources to keep the Zig type surface aligned.
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.
/zig/docs
Installation, quick start, PostgreSQL driver internals, security hardening, parity notes, benchmark methodology, and API reference.
/zig/changelog
Dedicated qail-zig release history so Zig progress does not get buried inside the Rust workspace changelog.
Quick start
Fastest path from dependency install to a working PgDriver connection and AST-native query in Zig.
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.6.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.6.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 27, 2026 three-way PostgreSQL snapshot, qail-zig leads prepared single-query and pool10 throughput, while qail.rs leads prepared pipeline throughput. Full methodology and raw output live at /zig/docs/benchmarks.html.
| Mode | Outcome | Read |
|---|---|---|
| Single (prepared, 1 conn) | qail-zig leads | Fastest mode for Zig in the March 27, 2026 public three-way PostgreSQL snapshot. |
| Pipeline (prepared batch, 1 conn) | qail.rs leads | Rust remains ahead on the current prepared pipeline hot path. |
| Pool10 (prepared singles, 10 conns) | qail-zig leads | Zig is ahead in the current pooled single-query run set. |
FAQ
Is qail-zig still deferred?
No. The PostgreSQL driver, pooling, TLS, COPY, CLI, LSP, hardening work, and benchmark harnesses are all public and part of the active Zig track.
Where should I send engineers first?
Start with /zig/docs for onboarding and operational reference, then use /zig for positioning and /zig/changelog for the release track.
What is the relationship to qail.rs?
qail.rs remains the broader reference platform and parity target. qail-zig is the dedicated pure Zig PostgreSQL runtime track built to stay aligned without collapsing the two surfaces into one page.
Where do the benchmark details live?
Use /zig/docs/benchmarks.html for the full Zig benchmark write-up and /benchmarks for the unified benchmark index across the rest of the site.