zero-postgres

PostgreSQL client bindings for the Zero programming language, wrapping libpq via Zero's C interop layer.

This is the first PostgreSQL package for Zero. It is at skeleton stage — the FFI call wiring is stubbed pending verification of Zero v0.1.1's C interop call syntax for pointer-returning functions and out-pointer patterns.

Status

• zero check --json passes (Zero v0.1.1, darwin-x64)
• C function calls are marked // SKELETON in each module
• All wrapper shapes, enums, choice types, and control flow are complete
• Replace SKELETON sections once out-pointer FFI syntax is confirmed

How to Build

Run from the repo root:

zero test zero.json          # run the 68 guard/type tests
zero check --json .          # type-check without building
zero build --out .zero/out/zero-postgres .

The package links against libpq dynamically. On macOS with MacPorts:

sudo port install postgresql16

On Linux:

apt install libpq-dev

The zero.json declares "pkg_config": "libpq" so the compiler can discover include and library paths via pkg-config libpq.

API Surface

All symbols are in flat scope after use. Functions use the pg prefix to avoid collisions when a consuming package uses multiple modules.

connection.0

use connection

// Open a connection
let result = pgConnect("host=localhost dbname=mydb user=me password=secret")
match result {
    .connected => conn { ... }
    .failed => msg { ... }
}

// Check status
pgStatus(&conn) -> Bool

// Get last error
pgErrorMessage(&conn) -> String

// Close
pgClose(&mut conn) -> Void

Shapes and choices:

shape PgConnection { handle: usize }

choice PgConnectResult {
    connected: PgConnection,
    failed: String
}

query.0

use query

let exec_result = pgExec(&conn, "SELECT id, name FROM users")
match exec_result {
    .rows => qr {
        let nr = pgRowCount(&qr)
        let nc = pgFieldCount(&qr)
        let col_name = pgFieldName(&qr, 0)
        let val = pgGetValue(&qr, 0, 0)
        pgClear(&mut qr)
    }
    .failed => msg { ... }
}

Shapes and choices:

shape PgQueryResult { handle: usize, nrows: i32, ncols: i32 }

choice PgExecResult {
    rows: PgQueryResult,
    failed: String
}

ffi.0

Low-level enum helpers for mapping C integer return codes:

enum ConnStatus { ok, bad }
enum ExecStatus { commandOk, tuplesOk, fatalError, other }

pgConnStatusFromInt(code: i32) -> ConnStatus
pgExecStatusFromInt(code: i32) -> ExecStatus

C Functions Wrapped

From libpq-fe.h:

C function	Zero wrapper
PQconnectdb	pgConnect
PQstatus	pgStatus
PQerrorMessage	pgErrorMessage
PQfinish	pgClose
PQexec	pgExec
PQresultStatus	internal in pgExec
PQntuples	internal in pgExec
PQnfields	internal in pgExec
PQgetvalue	pgGetValue
PQfname	pgFieldName
PQclear	pgClear

Vendored Header

vendor/include/libpq-fe-stub.h is a minimal stub declaring only the functions above. It is used for Zero compiler type-model extraction. The real libpq is linked at build time.

Known Limitations (Skeleton Stage)

• Out-pointer FFI pattern (for functions that return handles via ** params) is not yet verified in Zero v0.1.1
• String to const char* mapping through the libpq alias is unverified
• char* return values from C may require explicit span conversion

License

Apache-2.0. The libpq library itself is released under the PostgreSQL License.