Contributing to pgGraph

pgGraph is a PostgreSQL extension written in Rust with pgrx. The authoritative product and implementation documentation lives in docs/user_guide and docs/contributor_guide. Implementation work should keep code, SQL behavior, and docs aligned.

Development Setup

git clone https://github.com/evokoa/pggraph.git
cd pggraph/graph
cargo pgrx init
cargo test --features pg17
cargo pgrx test pg17

cargo pgrx init with no arguments builds PostgreSQL from source and needs ICU, pkg-config, bison, flex, readline, zlib, openssl, and perl on the host. On macOS the typical prerequisites are:

brew install icu4c pkg-config bison flex readline zlib openssl@3
export PKG_CONFIG_PATH="$(brew --prefix icu4c)/lib/pkgconfig:$PKG_CONFIG_PATH"

To skip the source build entirely, point pgrx at an existing PostgreSQL install:

cargo pgrx init --pg17 $(brew --prefix postgresql@17)/bin/pg_config

Use PostgreSQL 14 through 18 when validating compatibility-sensitive changes. PostgreSQL 13 has reached upstream EOL and is no longer an official support target, though the legacy pg13 pgrx feature remains available best-effort. The default local feature is pg17.

Nix devshell (optional)

A flake.nix is provided for contributors who use Nix. It pins the Rust toolchain, cargo-pgrx, and a Postgres major matching the pgrx feature flag, and initializes cargo pgrx against the nix-provided Postgres on first entry for the selected major — no system deps to install.

nix develop          # default shell: pg17
nix develop .#pg16   # switch majors
cd graph && cargo test --features pg17

With direnv installed, direnv allow activates the shell automatically. The Nix path is opt-in; the brew/apt paths above remain fully supported.

Pull Request Bar

  • Keep SQL APIs aligned with docs/user_guide/api-reference.mdx.
  • Add Rust unit tests for engine/data-structure changes.
  • Add pgrx SQL tests for public SQL behavior, ACLs, SQLSTATEs, sync, and persistence behavior.
  • Run cargo fmt --check before submitting.
  • Include Criterion or SQL benchmark results for performance-sensitive changes.
  • Update user-guide docs for SQL or operational behavior changes.
  • Update contributor-guide docs for storage, loader, memory model, safety, or internal architecture changes.

Scope

Accepted changes include bug fixes, crash-safety improvements, SQL API conformance, memory/performance improvements, tests, docs, examples, and benchmarking improvements.

Out of scope for V1 are new graph query languages, distributed consensus, runtime dependencies outside PostgreSQL/Rust, and features that require a separate graph service outside PostgreSQL.