gem-hunter
Language: Rust
Open-source graph database superpowers for your existing Postgres data.
Graph database superpowers for your existing Postgres data.
Your tables stay the source of truth. pgGraph builds a derived graph index and
lets you query it from SQL using functions in the graph schema.
Note
PostgreSQL 19 and SQL/PGQ: PostgreSQL removed SQL/PGQ from the PostgreSQL 19 release branch on September 7, 2026. See the official revert commit and release-management discussion. pgGraph supports PostgreSQL 14–18 and does not depend on native SQL/PGQ. Future native integration has no committed PostgreSQL target version.
Tip
Looking for a managed version? We have launched a managed version of pgGraph on polygres.com for full high performance GraphRAG on Postgres.
pgGraph 1.2.1 focuses on stability, synchronization, and database isolation.
Upgrading requires updating the extension and rebuilding each graph; see
release notes.
PostgreSQL is great at relational queries, but graph-style questions often require custom recursive SQL for each schema:
pgGraph adds graph queries on top of your existing PostgreSQL tables, without requiring a separate graph database, graph-specific storage system, or a new query language.
The repository quickstart builds a disposable PostgreSQL 17 image:
git clone https://github.com/evokoa/pggraph.git
cd pggraph
scripts/quickstart.shUse the versioned multi-architecture release image
ghcr.io/evokoa/pggraph:1.2.1. Verify its published digest before deployment.
Verify the extensions are loaded (uses psql inside the container, so you
don't need a local PostgreSQL client):
docker exec pggraph psql -U postgres -d graph \ -c "SELECT extname, extversion FROM pg_extension WHERE extname IN ('graph', 'pg_cron');"
If you have psql installed locally you can also connect directly:
psql -h localhost -U postgres -d graph
The Evokoa Homebrew tap is the convenience channel for local PostgreSQL 17 extension installs.
brew tap Evokoa/tap
brew install pggraph
brew test pggraphCreate and verify the extension in a local database:
brew services start postgresql@17 psql -d postgres -c "CREATE EXTENSION graph;" psql -d postgres -c "SELECT extname, extversion FROM pg_extension WHERE extname = 'graph';"
The Homebrew tap is updated separately from the Docker and PGXN channels.
For this release, verify that the installed extension reports version 1.2.1.
To build from source or run the full interactive demo instead, use the included quickstart script. It starts a disposable Docker-backed PostgreSQL database, installs pgGraph, creates two normal PostgreSQL tables, discovers the foreign key relationship, builds the graph, and runs example queries. If the image's scheduled maintenance is already active, the demo waits for that bounded operation to finish before building instead of failing with a transient lock.
You need Docker or Docker Desktop installed and running:
git clone https://github.com/evokoa/pggraph.git cd pggraph # run the full quickstart demo scripts/quickstart.sh # install into existing Postgres Docker container scripts/quickstart.sh docker my-postgres 17 appdb postgres # source build/install with pgrx into local PostgreSQL scripts/quickstart.sh pgrx # start Streamlit playground with a preset dataset and mode (csr|mutable) scripts/quickstart.sh playground panama csr scripts/quickstart.sh playground panama mutable
Supported modes:
quickstart / demo: build and start the Docker Postgres service, load demo
data, and run example graph queries. This is the default mode.setup: build and start Postgres with pgGraph installed, but do not load the
sample graph.psql: build and start Postgres, prepare demo data, then open psql.docker CONTAINER [PG_MAJOR] [DB_NAME] [DB_USER]: install pgGraph into an
existing running Postgres Docker container via
scripts/install_into_docker_postgres.sh.pgrx [PG_MAJOR]: build and install pgGraph into a local PostgreSQL using
cargo pgrx install.playground [panama|ldbc] [csr|mutable]: start the Streamlit playground
using a preset dataset and projection mode.clean: stop the Compose database and remove its volume.The script works on macOS and Linux from a normal terminal, and on Windows from WSL2 or Git Bash with Docker Desktop. It is not a native PowerShell or Command Prompt script.
Docker images are published for PostgreSQL 14 through 18. Tags without a
PostgreSQL major, such as 1.2.1 and latest, use the default PostgreSQL 17
image.
PostgreSQL 13 is no longer an official support target after upstream EOL, though
the legacy pg13 pgrx feature remains available on a best-effort basis. The
PostgreSQL major version of the extension package must match the target server.
For PGXN installation, use the verified source ZIP from the signed 1.2.1 release bundle. Because pgGraph is a Rust/pgrx extension, building from source requires the Rust toolchain.
pg_config1.96, pinned by graph/rust-toolchain.toml)cargo-pgrx 0.19.1cargo install cargo-pgrx --version 0.19.1 --locked # Register the installed PostgreSQL with pgrx (auto-detects the major): PG_MAJOR=$(pg_config --version | sed -E 's/[^0-9]*([0-9]+).*/\1/') cargo pgrx init --pg${PG_MAJOR}="$(which pg_config)" pgxn install pgGraph
git clone https://github.com/evokoa/pggraph.git cd pggraph make install # may need sudo psql -d postgres -c "CREATE EXTENSION graph;"
If you have multiple PostgreSQL installations, set PG_CONFIG to the target
server's pg_config, then re-run the installation:
export PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
make installIf sudo is needed for make install, preserve PG_CONFIG:
sudo --preserve-env=PG_CONFIG make install
If compilation fails with fatal error: postgres.h: No such file or directory,
install the PostgreSQL server development package for the target PostgreSQL
major, such as postgresql-server-dev-17 on Ubuntu or Debian.
Note: The PGXN distribution name is
pgGraphbut the PostgreSQL extension name isgraph. UseCREATE EXTENSION graph;after installation.
More information is available in the pgGraph docs:
Overview · Quickstart · Installation · Playground · Querying · SQL API
pgGraph is not "Postgres plus graph syntax." It is a cache-friendly graph execution layer for data that already lives in your ordinary relational tables.
The core idea is simple but powerful: keep PostgreSQL as your system of record, but build a highly optimized, read-heavy graph runtime from that relational metadata. The result is closer to a rebuildable graph index than a graph database: it is built from Postgres tables, operated with Postgres controls, and optimized for repeated bounded traversal over known topology.
Graph traversals usually die on recursive SQL queries or endless joins. pgGraph bypasses this by compiling your relational data into a specialized memory structure.
graph.build() compiles your relationships into
forward and reverse compressed sparse row (CSR) edge stores. A node's
neighbors are stored as a contiguous array slice. Instead of rediscovering
relationships via SQL, traversals are executed as raw, graph-native memory
scans.EdgeTypeId
values from adaptive one-, two-, or four-byte storage, typed FilterIndex
values, tenant bitmaps, active bits, and sync overlays..pggraph artifacts are written
atomically. When a new Postgres backend spins up, it validates the artifact
and copies it into a backend-local anonymous mapping before exposing immutable
forward graph arrays and the resolution index through read-only views. The
private snapshot prevents a concurrent write or truncation of the source file
from invalidating live Rust references. It also means each backend that loads
a graph retains approximately one artifact-sized private snapshot; base graph
pages are not shared across backends through the operating system page cache.
This is not a replacement for PostgreSQL's buffer pool: PostgreSQL remains
responsible for table storage, WAL, MVCC, durability, and crash recovery,
while pgGraph's artifact is derived state that can be rebuilt from source
tables.Your application data does not move. Source tables, constraints, indexes, ACLs, RLS, backups, and app writes remain 100% standard PostgreSQL concerns.
pgGraph is strictly derived state. You run the algorithms over internal node indexes, and the engine returns source table coordinates or hydrates the raw PostgreSQL rows on the fly. Build, sync, vacuum, and maintenance operations are fully visible and SQL-callable.
Apache AGE is a property graph database inside Postgres. It uses graph
namespaces, vertex and edge tables, agtype, and openCypher.
pgGraph does not ask you to move your data or learn Cypher. You keep your
existing schema and accelerate it with SQL functions like graph.search() and
graph.shortest_path(). Use AGE for a dedicated property graph model; use
pgGraph to add bounded, high-speed graph traversal to an existing relational
schema.
PostgreSQL removed SQL/PGQ, including CREATE PROPERTY GRAPH and GRAPH_TABLE,
from its PostgreSQL 19 release branch. The official
revert commit
links the upstream discussion. Native SQL/PGQ integration has no committed
PostgreSQL target version in pgGraph's roadmap.
pgGraph supports PostgreSQL 14–18 independently of native SQL/PGQ. It precomputes CSR adjacency stores and rebuildable artifacts for workloads that repeatedly traverse the same topology with bounded depth, path limits, filters, tenants, and application pagination. PostgreSQL 19 compatibility is tracked separately on the public roadmap.
pgGraph is built by Evokoa. Follow the project through the links at the top of this README.
Apache-2.0. See LICENSE.