QAIL-Zig | PostgreSQL Driver for Zig

35,305

Queries/sec (single)

315,708

Queries/sec (pipeline)

95%

of Native Rust Speed

Features

🔒 TLS 1.3

Full encryption using std.crypto.tls. No OpenSSL, no FFI.

🏊 Connection Pool

Background reconnect thread, URI parsing. Production-ready pooling.

📋 Rich Type System

UUID, INET/CIDR, Numeric, Timestamp, JSON/JSONB, Array iterators.

📡 LISTEN/NOTIFY

Pub/sub via AST: QailCmd.listen("events"), QailCmd.notifyChannel().

⚡ Pipeline Batching

Send 10,000 queries in one TCP write. 315K queries/sec.

🦎 Zero Dependencies

Pure Zig. Uses std.net, std.crypto. No tokio, no libc.

Benchmark vs pg.zig

Driver	Mode	Queries/sec	Ratio
QAIL-Zig	Single query	35,305 🏆	2.1x
pg.zig	Single query	16,832	1.0x
QAIL-Zig	Pipeline (1000/batch)	315,708 🚀	18.8x

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Your Zig Code                                                   │
│  ├── qail.encodeSelect("users", "id,name", 10)                  │
│  └── qail.encodePreparedBatch("stmt", params, 1000)             │
├─────────────────────────────────────────────────────────────────┤
│  Pure Zig Implementation               (zero dependencies)      │
│  ├── AST → Wire Protocol Encoding     (native Zig)              │
│  ├── TLS 1.3 via std.crypto.tls       (no OpenSSL)              │
│  └── Connection Pool + Background     (production-ready)        │
├─────────────────────────────────────────────────────────────────┤
│  Zig Native I/O                                                  │
│  ├── std.net.tcpConnectToAddress()                              │
│  └── stream.write() / stream.read()                             │
├─────────────────────────────────────────────────────────────────┤
│  PostgreSQL                             Wire Protocol            │
└─────────────────────────────────────────────────────────────────┘

Installation

📦 Step 1: Add to build.zig.zon

// In your project's build.zig.zon, add to .dependencies:
.dependencies = {
    .qail_zig = {
        .url = "https://github.com/qail-io/qail-zig/archive/refs/tags/v0.2.0.tar.gz",
        .hash = "...", // Run zig fetch to get this
    },
},

🔧 Step 2: Fetch the Package

# This downloads the package and outputs the hash
zig fetch --save https://github.com/qail-io/qail-zig/archive/refs/tags/v0.2.0.tar.gz

# The hash will be added to your build.zig.zon automatically!

⚙️ Step 3: Update build.zig

const std = @import("std");

pub fn build(b: *std.Build) void {
    const exe = b.addExecutable(.{
        .name = "my-app",
        .root_source_file = b.path("src/main.zig"),
        .target = b.standardTargetOptions(.{}),
        .optimize = b.standardOptimizeOption(.{}),
    });

    // Add QAIL - pure Zig, no FFI needed!
    const qail = b.dependency("qail_zig", .{});
    exe.root_module.addImport("qail", qail.module("qail"));

    b.installArtifact(exe);
}

🚀 Step 4: Use QAIL in Your Code

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

pub fn main() !void {
    // Connect to PostgreSQL with TLS
    var driver = try qail.PgDriver.connect(.{
        .host = "localhost",
        .port = 5432,
        .user = "postgres",
        .password = "secret",
        .database = "mydb",
        .tls = true,
    }, std.heap.page_allocator);
    defer driver.close();

    // Execute a query
    const rows = try driver.query("SELECT id, name FROM users");
    for (rows) |row| {
        std.debug.print("id={}, name={s}\n", .{
            row.get(i32, 0),
            row.getString(1) orelse "null",
        });
    }
}

View on GitHub 50M Benchmark Details