Debugging, CI and releasing
Attaching a debugger to a backend, editor setup, the CI scripts, troubleshooting and the release process.
13. Debugging
Section titled “13. Debugging”In-server unit tests
Section titled “In-server unit tests”Because Postgres forks a backend per connection, attach a debugger to a running session:
psql -U postgresSELECT pg_backend_pid(); -- e.g. 14985DROP FUNCTION IF EXISTS run_tests;CREATE FUNCTION run_tests() RETURNS INTEGERAS '$libdir/pgzx_unit' LANGUAGE C IMMUTABLE;Then attach (lldb -p 14985, gdb -p 14985, or VS Code) and run
SELECT run_tests();.
VS Code
Section titled “VS Code”Use the CodeLLDB extension and attach to the backend PID. Start VS Code from a shell that has the project environment so it inherits it:
eval "$(pgzx env)"code .If a VS Code instance is already running, the code launcher forwards to it
and the environment is not updated; quit VS Code first. The repository ships a
.vscode/launch.json with two configurations:
Attach to Postgres backend: prompts for the PID and attaches.Attach to Postgres backend (unit tests): same, but runs theext: build unit libtask first so the{name}_unitlibrary is installed into the server libdir with-p "$PG_HOME".
.vscode/tasks.json provides ext: build, ext: build unit lib and
ext: pg_regress with a picker for the example.
For the production library, load it and call a function:
LOAD 'char_count_zig';SELECT char_count_zig('aaabc', 'a');To debug a unit test suite, open a psql session, get the PID, run the
Attach to Postgres backend (unit tests) configuration (it rebuilds the
{name}_unit library first), then:
DROP FUNCTION IF EXISTS run_tests;CREATE FUNCTION run_tests() RETURNS INTEGERAS '$libdir/char_count_zig_unit' LANGUAGE C IMMUTABLE;SELECT run_tests();Editor setup (ZLS)
Section titled “Editor setup (ZLS)”If the editor shows (unknown) for @import("pgzx"), ZLS could not evaluate
build.zig. The pgzx build runs pg_config and translates the Postgres
headers at configure time, so ZLS must run with the environment from
eval "$(pgzx env)". Symptoms are translate-c errors such as
'postgres.h' not found in the ZLS output panel.
- Start the editor from a shell where
eval "$(pgzx env)"has been run, or rely on direnv (the project.envrccallspgzx env). - Install
zlsand put it onPATHso the editor extension can find it. zls.jsonenables build-on-save so the project is re-indexed withzig build check.- Restart the extension host after changing the environment.
PostgreSQL debug build
Section titled “PostgreSQL debug build”For stepping into PostgreSQL itself, build it from source (needs git, meson,
ninja, ccache and a C toolchain):
pgbuildexport PG_CONFIG="$PRJ_ROOT/out/local/bin/pg_config"eval "$(pgzx env)"This checks out PostgreSQL into out/postgresql_src and installs a debug build
into out/local.
Zig standard library / compiler
Section titled “Zig standard library / compiler”ziglocal clone --branch 0.16.0zig build unit -p "$PG_HOME" --zig-lib-dir "$PRJ_ROOT/out/zig/lib"The extra tooling for building the Zig compiler and PostgreSQL from source (clang, llvm, meson, ninja, ccache) must be installed on the host.
Testing Zig code with LLDB
Section titled “Testing Zig code with LLDB”@jacobly0 maintains a fork of LLDB with Zig support: https://github.com/jacobly0/llvm-project/tree/lldb-zig.
The fork only contains changes for debugging programs compiled by Zig’s
self-hosted backends, i.e. zig build-exe -fno-llvm .... Extensions built with
Zig’s LLVM backend (the default) are better served by vanilla LLDB built against
the LLVM version your Zig uses.
To build the fork, install the prerequisites, then:
cmake llvm -G Ninja -B build \ -DLLVM_ENABLE_PROJECTS="clang;lldb" \ -DCMAKE_BUILD_TYPE=Release \ -DLLVM_ENABLE_ASSERTIONS=ON \ -DLLDB_ENABLE_LIBEDIT=ON \ -DLLDB_ENABLE_PYTHON=ONcmake --build build --target lldb --target lldb-serverYou may need to configure dependencies manually if CMake cannot find them. Once
built, run ./build/bin/lldb.
Pretty printers
Section titled “Pretty printers”If you are debugging the Zig compiler itself, or anything compiled with Zig’s
LLVM backend, lldb/pretty_printers.py in Zig’s installed lib directory gives
a better experience. Add this to ~/.lldbinit:
command script import /path/to/zig/lib/lldb/pretty_printers.pyFor a Zig compiler built with the self-hosted backends:
type category enable zig.compilerFor Zig’s LLVM backend (with the fork, which is not recommended; prefer vanilla LLDB matching Zig’s LLVM version):
type category enable zig.langtype category enable zig.stdAnd when debugging a Zig compiler built with the LLVM backend without the fork:
type category enable zig14. CI
Section titled “14. CI”The CI is a shell script and works the same locally:
./ci/setup.sh # zig build cli + eval "$(pgzx env)" + pgzx init./ci/run.sh # build all examples, run pgzx unit tests and every exampleci/run.sh builds all examples in parallel, starts the server, runs the pgzx
unit tests, then runs each example’s ci/run.sh (build, create extension, unit
tests, regression tests, drop). It prints Success! on success.
The GitHub workflows run the same flow against PGDG packages for PostgreSQL
15–19, plus end-to-end jobs and a release gate (release.yaml calls
check.yaml):
lint: shellcheck, shfmt and actionlint (the same tools as the local.pre-commit-config.yaml).test: the repo’sci/setup.sh/ci/run.shon every supported PostgreSQL version.linux: installs the release bundle withinstall.sh --local, then scaffolds, builds, and runs unit + regression tests.macos: Homebrew PostgreSQL 19 + Zig, runspgzx doctorand compiles the template.templates: scaffolds the template and asserts the release stamping writes the tag URL and package hash.
15. Troubleshooting
Section titled “15. Troubleshooting”| Symptom | Cause / fix |
|---|---|
failed to spawn .../pg_regress: FileNotFound |
pg_config --pkglibdir does not contain the pgxs tooling; the build now derives pg_regress from pg_config --pgxs |
could not access file "foo_unit" |
the unit library was not installed into the server libdir; run zig build -p "$PG_HOME" unit |
cannot create cluster state ... |
the PostgreSQL prefix is read-only; set PGZX_CLUSTER_DIR to a writable directory (or use pgzx env, which does) |
SET outside the valid range instead of clamping |
core validates min/max before check hooks; widen the bounds |
server closed the connection unexpectedly |
a crash (e.g. a NULL value address); check out/pg/postgres/log/server.log |
(unknown) for pgzx imports in the editor |
ZLS is missing the environment from eval "$(pgzx env)"; see Editor setup |
stale weird errors after changing PG_CONFIG |
rm -rf .zig-cache in the package and rebuild |
Useful commands:
SHOW client_min_messages; -- what is sent to the clientSHOW log_min_messages; -- what is written to the server logThe server log is at $PGZX_CLUSTER_DIR/postgres/log/server.log
(out/pg/postgres/log/server.log by default).
16. Releasing
Section titled “16. Releasing”tools/build-dist.sh cross-compiles the CLI and writes these into dist/:
| Artifact | Notes |
|---|---|
pgzx-cli-<tag>-aarch64-macos.tar.gz |
Apple silicon |
pgzx-cli-<tag>-x86_64-macos.tar.gz |
Intel macOS |
pgzx-cli-<tag>-aarch64-linux-musl.tar.gz |
Linux arm64, statically linked |
pgzx-cli-<tag>-x86_64-linux-musl.tar.gz |
Linux x86_64, statically linked |
pgzx-template-<tag>.tar.gz |
project template |
install.sh |
target-detecting installer |
SHA256SUMS |
checksums for every archive |
Build them locally with the package hash of the tagged source tarball:
hash=$(zig fetch https://github.com/barddoo/pgzx/archive/refs/tags/vX.Y.Z.tar.gz | tail -n1)tools/build-dist.sh --version vX.Y.Z --hash "$hash"PGZX_TARGETS limits the target list while iterating, for example
PGZX_TARGETS="aarch64-macos" tools/build-dist.sh .... The script also builds a
host bundle at dist/cli/, which is what install.sh --local uses.
Test the bundle before tagging:
prefix=$(mktemp -d)./install.sh --local dist --prefix "$prefix""$prefix/bin/pgzx" versiondemo=$(mktemp -d) && (cd "$demo" && "$prefix/bin/pgzx" new demo --no-fetch)Publishing:
- Push a
vX.Y.Ztag..github/workflows/release.yamlre-runscheck.yaml, runsbuild-dist, and uploads everydist/*.tar.gz,SHA256SUMSandinstall.shto the GitHub release. - Render
dev/homebrew/pgzx.rb: setversionand the foursha256values fromdist/SHA256SUMS, then copy it tobarddoo/homebrew-tap/Formula/pgzx.rb. - Users install with
brew install barddoo/tap/pgzxor the releaseinstall.sh.install.shdetects the host target;PGZX_TARGEToverrides it for cross-installs.