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.
  • Review whether the change affects a documented SQL signature or result shape, GUC, SQLSTATE/diagnostic, catalog migration, artifact format, script contract, upgrade, rebuild, deprecation, or rollback guarantee. Mark breaking changes explicitly and update the compatibility inventory and release notes.

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.