Quickstart
This walks through the project pgzx new generates. For installing the pgzx
command and PostgreSQL itself, see Installation.
Scaffold and start
Section titled “Scaffold and start”pgzx doctor # check Zig, pg_config, headers, writable dirspgzx new my_extensioncd my_extensioneval "$(pgzx env)" # or: direnv allowpgzx init && pgzx start # throwaway cluster in ./out/pgzig build -p "$PG_HOME" # install into the running PostgreSQLpgzx env derives PG_HOME from pg_config and keeps cluster state in
./out/pg, so nothing is written into the PostgreSQL installation. It also
exports PGDATA, PGPORT, PGUSER and PGDATABASE from the cluster that
init created, so psql needs no connection flags.
Call it from SQL
Section titled “Call it from SQL”psql -U postgres -c 'CREATE EXTENSION my_extension'psql -U postgres -c 'SELECT hello()'CREATE EXTENSION works because -p "$PG_HOME" installed the .so, the control
file and the generated SQL script into the server’s lib and
share/postgresql/extension directories.
Where the code lives
Section titled “Where the code lives”The template splits an extension into three files:
src/ functions.zig pure function definitions; no exports, no registration schema.zig the pgzx_sql declaration; imports functions.zig main.zig PG_MODULE_MAGIC, PG_FUNCTION_V1, PG_EXPORT, raw C exportsmain.zig is what PostgreSQL loads. schema.zig is read at build time by the
SQL generator, which derives each CREATE FUNCTION from the Zig signature. A
minimal extension therefore looks like this:
pub fn hello() ![:0]const u8 { return "Hello, world!";}const functions = @import("functions.zig");
pub const pgzx_sql = .{ .functions = .{ .{ .name = "hello", .func = functions.hello }, },};const pgzx = @import("pgzx");const functions = @import("functions.zig");
comptime { pgzx.PG_MODULE_MAGIC(); pgzx.PG_FUNCTION_V1("hello", functions.hello);}The reasoning behind the split, and the full set of schema fields and build steps, is in Build system. A complete worked example is in the appendix.
Run the tests
Section titled “Run the tests”zig build pg_regress # sql/ against expected/zig build -p "$PG_HOME" unit # in-server unit testspgzx stop shuts the cluster down. For the development loop, debugging and
PostgreSQL version switching, see
Build, test and ship.