Local environment
How to get a working Zig and PostgreSQL toolchain, a throwaway cluster, and the project environment loaded into your shell.
1. Prerequisites
Section titled “1. Prerequisites”- Zig 0.17 or newer: ziglang.org/download.
- PostgreSQL 15–19 with development headers. Debian/Ubuntu:
postgresql-server-dev-NN; macOS:postgresql@NN; Fedora:postgresql-devel. - A C toolchain and the OpenSSL/Kerberos headers (
libssl-dev libkrb5-dev, oropenssl@3 krb5on Homebrew). - Linux or macOS (x86_64 or aarch64).
- Optionally direnv to load the project environment automatically.
Install the pgzx command
Section titled “Install the pgzx command”macOS, with Homebrew:
brew install barddoo/tap/pgzxLinux, and macOS without Homebrew:
curl -fsSL https://github.com/barddoo/pgzx/releases/latest/download/install.sh | shexport PATH="$HOME/.local/bin:$PATH"Check the environment before going further:
pgzx doctorIt reports Zig, pg_config, the server headers, the extra C headers needed by
the PostgreSQL header translation, and whether the extension directories are
writable. Each failure is printed with the command that fixes it.
Option A: Homebrew (macOS)
Section titled “Option A: Homebrew (macOS)”brew install postgresql@18 openssl@3 krb5 zigbrew link --force postgresql@18Homebrew has no postgresql@19 formula yet; 18 is the newest available there.
For 19, use the Docker image or the PGDG packages on Linux. Homebrew prefixes are
owned by your user, so installing the extension into PostgreSQL needs no elevated
permissions.
Option B: Raw install (Linux)
Section titled “Option B: Raw install (Linux)”Install Zig from ziglang.org/download and put
it on PATH:
ZIG_VERSION=0.17.1curl -fsSL "https://ziglang.org/download/${ZIG_VERSION}/zig-x86_64-linux-${ZIG_VERSION}.tar.xz" \ -o /tmp/zig.tar.xzsudo tar -C /usr/local -xJf /tmp/zig.tar.xzsudo ln -s "/usr/local/zig-x86_64-linux-${ZIG_VERSION}/zig" /usr/local/bin/zigzig version # should print 0.17.1Install PostgreSQL and its development headers:
PG_MAJOR=19 # or 15 / 16 / 17 / 18curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \ | sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpgecho "deb [signed-by=/usr/share/keyrings/postgresql.gpg] \ https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \ | sudo tee /etc/apt/sources.list.d/pgdg.listsudo apt-get updatesudo apt-get install -y \ postgresql-${PG_MAJOR} \ postgresql-server-dev-${PG_MAJOR} \ libssl-dev libkrb5-devOn Fedora/RHEL:
sudo dnf install -y postgresql-server postgresql-devel openssl-devel krb5-develzig build -p "$PG_HOME" writes the shared library and the extension SQL into
the PostgreSQL prefix. Distro packages make those directories root-owned, so
give your user write access once:
sudo chown -R "$(id -un)" \ "$(pg_config --pkglibdir)" \ "$(pg_config --sharedir)/extension"(On Homebrew and in the Docker image this is not needed.)
Option C: Docker (nothing installed on the host)
Section titled “Option C: Docker (nothing installed on the host)”# Build once (~3 min; cached afterwards). Pick a PostgreSQL version if needed.docker build \ --build-arg PG_MAJOR=19 \ -f dev/docker/Dockerfile.standalone \ -t pgzx-standalone \ .
# Scaffold into the current directory, then work in the container.docker run -it --rm -v "$PWD:/work" -w /work pgzx-standaloneInside the container, Zig, PostgreSQL (with headers), and pgzx are already on
PATH. The extension directories are owned by the container’s dev user, so
zig build -p "$PG_HOME" works without sudo:
pgzx new my_extcd my_exteval "$(pgzx env)"pgzx init && pgzx startzig build -p "$PG_HOME"psql -U postgres -c 'CREATE EXTENSION my_extension'pgzx stopOr use Compose, which mounts the repository at /workspace:
docker compose -f dev/docker/docker-compose.yml run --rm devCreate and run the project (all options)
Section titled “Create and run the project (all options)”pgzx doctorpgzx new my_extcd my_exteval "$(pgzx env)" # or: direnv allowpgzx init && pgzx startzig build -p "$PG_HOME"psql -U postgres -c 'CREATE EXTENSION my_extension'psql -U postgres -c 'SELECT hello()'zig build -p "$PG_HOME" unitzig build pg_regresspgzx stoppgzx new uses templates/default. Cluster state lives in <project>/out/pg,
so nothing is written into the PostgreSQL installation. Use PG_CONFIG to
pick a PostgreSQL version (see 12).
2. Load the project environment
Section titled “2. Load the project environment”From a checkout, build the CLI once and put it on PATH:
zig build cliexport PATH="$PWD/zig-out/bin:$PATH"pgzx env prints shell exports for the project; evaluate them in the shell you
build from:
eval "$(pgzx env)"It derives PG_HOME, PGHOST, the socket directory, the include paths and a
shared Zig cache from pg_config, and prepends the PostgreSQL bin and
pg_regress directories to PATH. Run it again after changing PG_CONFIG.
With direnv, the generated project’s .envrc loads it automatically:
direnv allowThe commands are subcommands of the pgzx binary:
| Command | Purpose |
|---|---|
pgzx new <name> |
Create a new extension project |
pgzx env [cluster] |
Print the project environment |
pgzx init / start / stop / status |
Control the local cluster |
pgzx doctor |
Check Zig, PostgreSQL and headers |
pgzx fingerprint |
Refresh the package fingerprint |
3. Create the local PostgreSQL cluster
Section titled “3. Create the local PostgreSQL cluster”eval "$(pgzx env)"pgzx init # initdb + create the 'postgres' superuserpgzx start # start the serverpgzx status # show the server statuspsql -c 'select version()' # PGUSER/PGDATABASE come from pgzx envpgzx stop # stop the serverpgzx init ends by printing the cluster’s data directory, socket, log file,
port, user and database, plus the next commands to run.
Notes:
- Cluster state lives in
<project>/out/pg/postgres; it is independent of the PostgreSQL installation, so a read-only system prefix works.rm -rf out/pgresets the project’s clusters. pgzx envexportsPGHOST,PGDATA,PGPORT,PGUSER,PGDATABASEandPGZX_CLUSTERfrom<cluster>/cluster.conf(written byinit), sopsqlandpg_ctlwork without extra flags. Pass a cluster name to select one:eval "$(pgzx env mytest)".pgzx initaccepts optional arguments:Terminal window pgzx init <cluster> <database> <user>pgzx init -p 5433 # custom portpgzx init -s pg_stat_statements # shared_preload_librariespgzx init -i path/to/sql/dir # run *.sql on initpgzx init -c path/to/postgresql.conf # custom configpgzx init --force # delete the cluster and recreate itinitrefuses to overwrite an existing cluster unless--forceis given;--forcestops the server (if running) and deletes<cluster base>/<cluster>.- The Unix socket lives in
out/pg/run(not the compiled-in/run/postgresql), andPGHOSTpoints at it. Socket paths are limited bysun_path(107 bytes on Linux, 103 on macOS), soinit,startanddoctorreject an over-long path; setPG_SOCKET_DIR=/tmp/pgzx-<cluster>to shorten it. - Server logs are written to
out/pg/postgres/log/server.log. PGZX_CLUSTER_DIRmoves the cluster state andPG_SOCKET_DIRmoves the socket;pgzx envsets both under<project>/out/pgby default.start,stopandstatususe the cluster name argument, elsePGZX_CLUSTER, elsepostgres.
4. Repository layout
Section titled “4. Repository layout”build.zig top-level project (the pgzx library itself)build.zig.zonsrc/pgzx.zig the pgzx library entry pointsrc/pgzx/build.zig build helpers (PGBuild) used by extensionssrc/pgzx/c/ C shims and the Postgres header translationsrc/testing.zig entry point for the in-server unit test extensionexamples/ sample extensions, each its own packagedev/bin/ pgbuild and other host tooling (`pgzx` itself is built to zig-out/bin)templates/default/ the project template used by `pgzx new`tools/ codegen and release scripts (build-dist)out/ local cluster state (git-ignored)Every directory under examples/ is a self-contained Zig package with its own
build.zig and build.zig.zon, depending on pgzx via a path dependency.
5. Environment variables
Section titled “5. Environment variables”pgzx env sets these for you:
| Variable | Value | Meaning |
|---|---|---|
PRJ_ROOT |
project root | used by the CLI and tooling |
PG_HOME |
pg_config prefix |
the PostgreSQL installation in use |
PGHOST |
$PG_SOCKET_DIR |
Unix socket directory for clients |
PGDATA |
<cluster>/data |
data directory of the selected cluster |
PGPORT |
cluster.conf |
port of the selected cluster |
PGUSER |
cluster.conf |
role init created (postgres) |
PGDATABASE |
cluster.conf |
database init created (postgres) |
PGZX_CLUSTER |
resolved cluster name | cluster used when a command omits the name |
PGZX_CLUSTER_DIR |
<project>/out/pg |
cluster state |
PG_SOCKET_DIR |
$PGZX_CLUSTER_DIR/run |
Unix socket directory used by the server |
PGZX_C_INCLUDE_DIRS |
Homebrew paths | extra C headers for the header translation |
ZIG_LOCAL_CACHE_DIR |
~/.cache/zig-pgzx |
shared Zig cache for the whole repo |
PG_CONFIG |
optional | pg_config to use (default: pg_config) |
To work against a specific installation, point PG_CONFIG at its pg_config
before evaluating pgzx env.