pgzx internals
How src/pgzx/build.zig
implements the steps above, and why the SQL generator forces the three-file
split.
1. Two build scripts
Section titled “1. Two build scripts”There are two distinct build.zig files:
/build.zig: builds the pgzx library and its own test extension. It defines thepgzxmodule, translates the Postgres headers, generates node tags, builds docs, and runs the in-server pgzx tests./src/pgzx/build.zig: the reusable build helper API (Build,Project,InstallExtension, …) that extensions import as@import("pgzx").Build.
Root build script
Section titled “Root build script”pub const Build = @import("src/pgzx/build.zig");
pub fn build(b: *std.Build) void { const target = b.standardTargetOptions(.{}); const optimize = b.standardOptimizeOption(.{});
var pgbuild = Build.create(b, .{ .target = target, .optimize = optimize }); // ...}It then:
- Creates the
pgzx_pgsysmodule by runningtranslate-coversrc/pgzx/c/include/headers.h, adding the Postgresserver/includepaths, the shim headers, the host OpenSSL/Kerberos include paths, andPGZX_C_INCLUDE_DIRSfrom the environment. It compilessrc/pgzx/c/libpqsrv.cand linkslibpq. - Runs
tools/gennodetags/main.zigto generatenodetags.zig(a codegen input forsrc/pgzx/node.zig). - Creates the
pgzxmodule rooted atsrc/pgzx.zigwith importspgzx_pgsysand the anonymousgen_node_tagsmodule. - Builds docs, pure tests, the
pgzx_unittest extension, and the unit-test runner.
The Project.init helper is only used by extensions; the pgzx repo itself wires
its steps manually.
2. Build: the low-level helper
Section titled “2. Build: the low-level helper”Build (src/pgzx/build.zig) is created with Build.create(owner, .{ target, optimize, debug }).
Responsibilities:
- Locate PostgreSQL paths lazily via
pg_config(runPGConfig), with caching inBuild.paths:getIncludeDir,getIncludeServerDir,getLibDir,getPackageLibDir,getSharedDir,getBinDir,getExtensionDir,getPGHome,getPGRegressPath,getPsqlPath.PG_CONFIGcan override the binary; otherwisepg_configfromPATHis used. Paths that must be relative to the install prefix (sharedir) are converted withmakeRelPath. - Provide modules to extensions:
modules.pgzx()andmodules.pgsys(), resolved throughstd_build.dependency("pgzx", options).module(name). - Create extension libraries:
addExtensionLib. - Install artifacts:
addInstallExtension,installExtension,addInstallExtensionLibArtifact,addInstallExtensionDir. - Run tests:
addRegress,addRunTests.
addExtensionLib
Section titled “addExtensionLib”Creates a dynamic library:
pub fn addExtensionLib(b: *Build, options: ExtensionLibOptions) *Step.Compile { const lib_module = b.std_build.createModule(.{ .root_source_file = resolveLazyPath(root_dir, options.root_source_file, "main.zig"), .target = b.options.target, .optimize = b.options.optimize, .link_libc = true, }); lib_module.addIncludePath(.{ .cwd_relative = b.getIncludeServerDir() });
const lib = b.std_build.addLibrary(.{ .name = options.name, .linkage = .dynamic, .version = .{ .major, .minor, .patch = 0 }, .root_module = lib_module, }); lib.linker_allow_shlib_undefined = true; // server symbols resolved at load return lib;}linker_allow_shlib_undefined = true is what lets the .so reference
palloc, errcode, and friends; the PostgreSQL backend resolves them when it
loads the library.
Installing the library
Section titled “Installing the library”addInstallExtensionLibArtifact computes the platform suffix (.so, .dylib)
and decides where to put the result. Normally the package libdir
(pg_config --pkglibdir) is inside $PG_HOME, so the artifact is installed at
the relative path under the prefix. For split installations (common with
distro -dev packages, where --pkglibdir may point elsewhere), it falls
back to installing directly at the prefix root. This logic protects against
deploying into the wrong tree when the install prefix is not $PG_HOME.
3. Project: the extension-facing helper
Section titled “3. Project: the extension-facing helper”Project bundles the configuration and provides convenience methods:
initvalidates/defaults the config, createsbuild_optionsandtest_build_options(thetestfngate), and loads thepgzxmodule.createLib(name, options)builds an extension library and callsconfigureLib, which attaches:- the
pgzximport, - the
build_optionsmodule and every module added viaaddOptions, - accumulated include paths, library paths, and C source files
(
addIncludePath,addLibraryPath,addCSourceFiles).
- the
extensionLib/installExtensionLib/installExtensionDirwrap the low-level install functions with the project’s name/version.addUnitTestsbuilds<name>_unitwithtestfn = trueand returns theSELECT run_tests()run step.addRegressTestsforwards toBuild.addRegress.addSchemais the SQL generator (next section).addStepsassembles the public steps.
addSteps produces:
zig build└── install (default) ├── install extension library -> $prefix/lib/<name>.so ├── install extension directory -> $prefix/share/postgresql/extension/* └── install generated SQL (optional) -> $prefix/share/postgresql/extension/<name>--<ver>.sql
zig build check -> compile the extension module onlyzig build sql -> install generated SQL onlyzig build unit -> <name>_unit + SELECT run_tests()zig build pg_regress -> pg_regress over the configured scripts4. SQL generation internals (Project.addSchema)
Section titled “4. SQL generation internals (Project.addSchema)”addSchema(options: SchemaOptions):
-
Resolve the source.
sourcedefaults to<root_dir>/schema.zig. -
Create the schema module. A
std.Build.Modulerooted at that file, built with.optimize = .ReleaseSmall, .strip = true, wired with thepgzximport,build_options, extra options, and include paths. The small/optimized build is essential (see §7). -
Synthesize the generator.
b.addWriteFiles()createspgzx_generate_sql.zig:const std = @import("std");const pgzx = @import("pgzx");const schema = @import("schema");pub fn main(init: std.process.Init) !void {var buffer: [64 * 1024]u8 = undefined;var stdout_writer = std.Io.File.stdout().writer(init.io, &buffer);const stdout = &stdout_writer.interface;try pgzx.ddl.render(stdout, schema.pgzx_sql);try stdout.flush();}The declaration name is substituted from
options.declaration(defaultpgzx_sql). This uses Zig 0.16’sstd.process.Init/std.IoAPI. -
Build the executable. A module importing
pgzxand theschemamodule, as anaddExecutable, also.ReleaseSmall/.strip. -
Capture and install.
b.addRunArtifact(exe).captureStdOut(.{ .basename = file_name })yields aLazyPath;addInstallFileWithDirinstalls it at$prefix/<getExtensionDir()>/<file_name>. The default file name is<name>--<major>.<minor>.sql.
The renderer
Section titled “The renderer”src/pgzx/ddl.zig:
Function(decl)normalizes an entry to a type with all fields present, using@hasFieldand comptime ternaries so that omitted fields fall back to defaults without being semantically analyzed.render(writer, schema)emits the optionalsqlpreamble and then loopsinline for (schema.functions).renderFunctionderives argument types from@typeInfo(fn).@"fn".params, skippingpg.FunctionCallInfo, unlessargsis set. Return type goes throughmeta.fnReturnType(unwrappingerror_union) anddatum.sqlType.- Type→SQL mapping is
src/pgzx/datum.zig:sqlType, which reads thesql_namefield attached to eachConvconverter.SimpleConvtakes the SQL name as a required comptime parameter, andConv/ConvNoFail/OptConvpropagate it, so optionals (?T) inheritT’s mapping.
The renderer is intentionally extensible: adding aggregates, triggers, or types
means adding another @hasField(schema, "...") branch and an emitter, without
changing the driver.
5. In-server unit tests
Section titled “5. In-server unit tests”-
Project.addUnitTestsbuilds a second library named<name>_unitwithbuild_options.testfn = true. -
main.zigcallspgzx.testing.registerTests(@import("build_options").testfn, .{...}), so the production library contains no test registration. -
Build.addRunTestsruns (viapsql):DROP FUNCTION IF EXISTS run_tests;CREATE FUNCTION run_tests() RETURNS INTEGER AS '$libdir/<name>_unit' LANGUAGE C IMMUTABLE;SELECT run_tests();
run_tests is itself a v1 fmgr function registered by
src/testing.zig; it walks every registered suite, runs functions named
test*, and reports the count.
6. pg_regress
Section titled “6. pg_regress”Build.addRegress locates pg_regress from pg_config --pgxs (deriving the
tool path from the pgxs makefile location, which keeps pg_regress consistent
with the same PostgreSQL tree as the headers even when split packages are
installed). It runs:
pg_regress --inputdir <root> --outputdir <root> --expecteddir <root> \ [--host ..] [--port ..] [--user ..] [--dbname ..] [--create-role ..] \ [--load-extension ..] <scripts...>and the pg_regress build step depends on install, so the .so, the control
file, and the generated SQL are in place before the tests run.
7. The linking constraint (why the three-file split exists)
Section titled “7. The linking constraint (why the three-file split exists)”PG_FUNCTION_V1("name", fn) does two things: it exports pg_finfo_<name>, and
it @exports a generated C-ABI wrapper that calls fn. @export makes the
symbol a linker root, so the wrapper, and therefore fn’s body, is emitted
even in release builds. Those bodies call server functions such as palloc,
errcode, CurrentMemoryContext, get_fn_expr_argtype, … .
A shared library may reference those symbols (linker_allow_shlib_undefined).
An executable may not: the dynamic linker would have nothing to bind them to.
Because addSchema must run a generator executable, the generator’s import
graph must not contain any @exported function body.
Concretely, this fails to link (observed):
error: undefined symbol: pfreeerror: undefined symbol: get_fn_expr_argtype...note: referenced by pgzx_generate_sql ... (hello_world_zig_datum)Two things were tried before settling on the split:
- Debug builds fail with references from
.debug_info; stripping removes that, but@exportstill emits.text. - Zig’s build API does not expose
--unresolved-symbols=ignore-all/-z undefs(only the opposite,-z defs), so the linker cannot be told to tolerate the unresolved symbols.
The fix is architectural: the generator imports only schema.zig (plus the
pgzx library), never main.zig. Functions are referenced solely as comptime
values in pgzx_sql, so the ReleaseSmall + strip generator build dead-strips
their bodies and no server symbol is referenced at link time. The schema module
therefore must not call PG_FUNCTION_V1/PG_EXPORT, which is exactly the rule
documented for extension authors in Part I.
8. Codegen inputs
Section titled “8. Codegen inputs”pgzx_pgsys: produced byaddTranslateCoversrc/pgzx/c/include/headers.hwith Postgres server headers, a PG15varatt.hshim, and host SSL/Kerberos includes. This is thepg/cnamespace used throughout pgzx and extensions.gen_node_tags:tools/gennodetags/main.zigparses Postgres node tag headers and emits a Zig enum/module used bysrc/pgzx/node.zig.
Both are created once in the root build script and threaded into the pgzx
module so every consumer sees the same generated code.
9. Extending the build
Section titled “9. Extending the build”- New library feature: add a module under
src/pgzx/, export it fromsrc/pgzx.zig, and (if it has server tests) register its suite insrc/testing.zig. - New schema object: add an emitter to
src/pgzx/ddl.zigand a branch inrenderkeyed on a new top-level field inpgzx_sql. - New SQL type: add a
sql_nameto the relevant converter insrc/pgzx/datum.zig, or teach a custom type’sConvto exposesql_name. - New build step: extend
Project.StepsOptions/addStepsand wire the step withb.step(...).