CONTRIBUTING.md instructs to run cargo pgrx init after cloning. With no args, pgrx builds Postgres from source, which pulls in a build-dep stack (ICU, bison, flex, readline, zlib, openssl, perl). On a fresh macOS box I hit:
configure: error: ICU library not found
Fixable with brew install icu4c + exporting PKG_CONFIG_PATH, but then the next contributor hits the same wall on bison, or readline, or a version skew between system Postgres and the pgrx feature flag. The Dockerfile already sidesteps this by passing --pg17=/usr/lib/postgresql/17/bin/pg_config, but the local-dev path doesn't.
Pinning matters here too: cargo-pgrx 0.18.0 is hard-coded in the Dockerfile, and contributors running a different version locally will see different behavior than CI.
solution
Opt-in Nix flake at the repo root, plus a .envrc for direnv users. Flake provides:
- Pinned cargo-pgrx matching the project version
- Postgres 13–18 as separate devShells (nix develop .#pg17, etc.)
PG_CONFIG, PGRX_HOME, PKG_CONFIG_PATH pre-set, and a shellHook that runs cargo pgrx init --pg17=$PG_CONFIG on first entry against the nix-provided Postgres, w/o src build or sys deps outside of the flake.
End state contributor flow:
git clone …
cd pggraph
direnv allow # or: nix develop
cd graph
cargo test --features pg17
Solves the ICU/bison/ect churn because the shell is dep set/same across darwin/linux w/ same pgrx version as CI (ci on nix out of scope but there are a couple decent options for nix caches. + switching PG majors is a shell selector)
Alternatives
- Documenting brew/apt deps in CONTRIBUTING.md — works, but every PG major and every OS adds another row to maintain, and version drift between system Postgres and the pgrx feature flag is its own footgun.
- Pointing pgrx at an existing brew/apt Postgres (
cargo pgrx init --pg17 $(brew --prefix postgresql@17)/bin/pg_config) - better than nada but doesn't pin cargo-pgrx or solve the darwin/linux split
- Docker-only dev via scripts/quickstart.sh - n/a imo for inner dev loop on cargo test/ rust analyzer.
Nix sits cleanly alongside these as an opt-in for people who want it; nothing forces it on contributors who don't have Nix installed.
Happy to open a PR if there's interest. Scope I'd propose:
- flake.nix, flake.lock, .envrc
- A short "Nix (optional)" section in CONTRIBUTING.md
- No changes to the existing brew/Docker paths
env:
- pgGraph: feat/cypher-frontend @ b904506
- Host: macOS (aarch64), Homebrew toolchain
- Target: cargo pgrx init / pg17
CONTRIBUTING.md instructs to run cargo pgrx init after cloning. With no args, pgrx builds Postgres from source, which pulls in a build-dep stack (ICU, bison, flex, readline, zlib, openssl, perl). On a fresh macOS box I hit:
configure: error: ICU library not foundFixable with
brew install icu4c+ exportingPKG_CONFIG_PATH, but then the next contributor hits the same wall on bison, or readline, or a version skew between system Postgres and the pgrx feature flag. The Dockerfile already sidesteps this by passing--pg17=/usr/lib/postgresql/17/bin/pg_config, but the local-dev path doesn't.Pinning matters here too: cargo-pgrx 0.18.0 is hard-coded in the Dockerfile, and contributors running a different version locally will see different behavior than CI.
solution
Opt-in Nix flake at the repo root, plus a .envrc for direnv users. Flake provides:
PG_CONFIG,PGRX_HOME,PKG_CONFIG_PATHpre-set, and a shellHook that runscargo pgrx init --pg17=$PG_CONFIGon first entry against the nix-provided Postgres, w/o src build or sys deps outside of the flake.End state contributor flow:
Solves the ICU/bison/ect churn because the shell is dep set/same across darwin/linux w/ same pgrx version as CI (ci on nix out of scope but there are a couple decent options for nix caches. + switching PG majors is a shell selector)
Alternatives
cargo pgrx init --pg17 $(brew --prefix postgresql@17)/bin/pg_config) - better than nada but doesn't pincargo-pgrxor solve the darwin/linux splitNix sits cleanly alongside these as an opt-in for people who want it; nothing forces it on contributors who don't have Nix installed.
Happy to open a PR if there's interest. Scope I'd propose:
env: