Overview
pgGraph is a PostgreSQL extension that lets you query existing relational
tables as a graph. It keeps Postgres as the system of record, builds an
in-memory graph index from registered tables and relationships, and exposes
traversal, search, pathfinding, and graph maintenance through standard SQL
functions in the graph schema.
CREATE EXTENSION graph;
SELECT * FROM graph.auto_discover('public');
SELECT * FROM graph.traverse('customers'::regclass, '42', 5);Why pgGraph Exists
Most relational databases already contain graph structure: primary keys are nodes, foreign keys are edges, and application tables hold the payloads. Recursive CTEs can traverse that structure, but they become hard to maintain and slow on large, connected datasets. External graph databases can be fast, but they add infrastructure, sync pipelines, operational overhead, and a new query language.
pgGraph targets the middle ground: graph traversal speed inside PostgreSQL, using SQL that application teams already understand.
What It Provides
| Capability | Description |
|---|---|
| Traversal | Breadth-first traversal from a source table and primary key. |
| Shortest path | Unweighted shortest path, plus weighted path support when an edge weight column is registered. |
| Search | Token and property search over registered node columns. |
| Path reconstruction | JSONB path and edge path output for explaining how a result was reached. |
| Connected components | Admin-oriented component discovery and summary functions. |
| Schema discovery | Registration from primary keys and foreign keys with manual overrides. |
| Sync | Trigger-based automatic sync for registered tables, with WAL-based sync documented as roadmap work. |
How Results Work
Traversal functions return graph coordinates such as source table, source primary key, depth, path, and optional hydrated row JSON. You can join those coordinates back to ordinary tables when you want full relational payloads:
SELECT c.name, c.email, g.depth, g.path
FROM graph.traverse('customers'::regclass, '42', 3) AS g
JOIN customers AS c ON c.id = g.node_id
WHERE g.node_table = 'customers'::regclass;This keeps payload authorization in PostgreSQL. Table privileges and row-level security apply when you hydrate or join source rows.
Start Here
- Quickstart builds a tiny graph and runs search, traversal, and shortest-path queries.
- Installation covers build, install, configuration, upgrade, and troubleshooting.
- SQL API is the function reference.
- Architecture, Sync, and Memory Model explain the internals.
- Security covers ACL, RLS, tenant scoping, index data, and operational boundaries.
- Demos show realistic query flows over the Panama Papers dataset.
Project Boundaries
pgGraph is a local graph acceleration layer for one PostgreSQL database. It is not a replacement for all graph systems.
| Supported | Not the target |
|---|---|
| Local neighborhood traversal | Global graph analytics such as PageRank or Louvain |
| Pathfinding and path explanation | Cypher, SPARQL, Gremlin, or GQL compatibility |
| SQL-first application integration | External graph storage as the system of record |
| PostgreSQL ACL/RLS integration | Cross-database federation |
| Single-instance PostgreSQL deployments | Distributed multi-node graph execution |
License
pgGraph is planned for public release under the Apache License 2.0.