{"id":50195248,"url":"https://github.com/Evokoa/pgGraph","last_synced_at":"2026-06-11T09:00:58.891Z","repository":{"id":357613437,"uuid":"1237524419","full_name":"Evokoa/pgGraph","owner":"Evokoa","description":"Open-source graph database superpowers for your existing Postgres data.","archived":false,"fork":false,"pushed_at":"2026-06-08T18:16:10.000Z","size":1742,"stargazers_count":391,"open_issues_count":4,"forks_count":30,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-06-08T19:25:00.500Z","etag":null,"topics":["ai","ai-agents","ai-agents-framework","graph","graph-database","pgrx","postgres","postgresql-database","postgresql-extension","relationship-graph","rust","traversal"],"latest_commit_sha":null,"homepage":"https://www.evokoa.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Evokoa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.mdx","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-13T09:04:07.000Z","updated_at":"2026-06-08T18:15:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Evokoa/pgGraph","commit_stats":null,"previous_names":["evokoa/pggraph"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Evokoa/pgGraph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evokoa%2FpgGraph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evokoa%2FpgGraph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evokoa%2FpgGraph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evokoa%2FpgGraph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Evokoa","download_url":"https://codeload.github.com/Evokoa/pgGraph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Evokoa%2FpgGraph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34190585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-agents-framework","graph","graph-database","pgrx","postgres","postgresql-database","postgresql-extension","relationship-graph","rust","traversal"],"created_at":"2026-05-25T17:00:40.039Z","updated_at":"2026-06-11T09:00:58.885Z","avatar_url":"https://github.com/Evokoa.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/pggraph-banner.png\" alt=\"pgGraph Banner\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003epgGraph    \u003ca href=\"https://docs.evokoa.com/pggraph/user_guide\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/docs-pgGraph-0ea5e9?style=flat-square\" alt=\"pgGraph documentation\"\u003e\n  \u003c/a\u003e\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eGraph database superpowers for your existing Postgres data.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/evokoa/pggraph/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/evokoa/pggraph?style=flat-square\u0026logo=github\u0026label=stars\" alt=\"GitHub stars\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/evokoa/pggraph/releases\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/version-0.1.7-2ea44f?style=flat-square\" alt=\"Version 0.1.7\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square\" alt=\"License: Apache-2.0\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.postgresql.org/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PostgreSQL-14--18-336791?style=flat-square\u0026logo=postgresql\u0026logoColor=white\" alt=\"PostgreSQL 14-18\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://ghcr.io/evokoa/pggraph\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Docker-ghcr.io%2Fevokoa%2Fpggraph-blue?style=flat-square\u0026logo=docker\u0026logoColor=white\" alt=\"Docker image\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/evokoa/pggraph/issues\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues/evokoa/pggraph?style=flat-square\u0026logo=github\u0026label=issues\" alt=\"GitHub issues\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/evokoa/pggraph/pulls\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/issues-pr/evokoa/pggraph?style=flat-square\u0026logo=github\u0026label=PRs\" alt=\"GitHub pull requests\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/evokoa/pggraph/commits/main\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/last-commit/evokoa/pggraph?style=flat-square\u0026logo=github\u0026label=last%20commit\" alt=\"Last commit\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://evokoa.com\" target=\"_blank\" rel=\"noreferrer\"\u003e\n  \u003cimg\n    src=\"https://img.shields.io/badge/Built%20by-Evokoa-ff6b35?style=for-the-badge\"\n    alt=\"Built by Evokoa\"\n  \u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://x.com/evokoa_ai\" target=\"_blank\" rel=\"noreferrer\"\u003e\n    \u003cimg\n      src=\"https://img.shields.io/badge/Follow%20on%20X-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white\"\n      alt=\"Follow on X\"\n    \u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://discord.gg/GnHR8ezuwG\" target=\"_blank\" rel=\"noreferrer\"\u003e\n    \u003cimg\n      src=\"https://img.shields.io/discord/1496159762704896022?style=for-the-badge\u0026label=Join%20Discord\u0026logo=discord\u0026logoColor=white\u0026color=5865F2\"\n      alt=\"Join the Evokoa Discord\"\n    \u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.producthunt.com/@evokoa\" target=\"_blank\" rel=\"noreferrer\"\u003e\n    \u003cimg\n      src=\"https://img.shields.io/badge/Follow%20on%20Product%20Hunt-DA552E?style=for-the-badge\u0026logo=product-hunt\u0026logoColor=white\"\n      alt=\"Follow on Product Hunt\"\n    \u003e\n  \u003c/a\u003e\n\u003c/p\u003e\npgGraph is a PostgreSQL extension for running graph search, traversal, shortest\npath, and relationship queries directly against ordinary PostgreSQL tables.\n\nYour tables stay the source of truth. pgGraph builds a derived graph index and\nlets you query it from SQL using functions in the `graph` schema.\n\n\u003e [!IMPORTANT]\n\u003e pgGraph is in early alpha. Even though we have tested it to be stable,\n\u003e please avoid production use for now; try it in\n\u003e Docker or a dedicated development database and share feedback to help the\n\u003e project grow.\n\n## Why pgGraph?\n\nPostgreSQL is great at relational queries, but graph-style questions often\nrequire custom recursive SQL for each schema:\n\n- “Find records related to Alice within 2 hops.”\n- “Find the shortest path between this person and this company.”\n- “Search nodes across registered tables.”\n\npgGraph adds graph queries on top of your existing PostgreSQL tables, without\nrequiring a separate graph database, graph-specific storage system, or a new\nquery language.\n\n## Quickstart\n\nThe fastest way to try pgGraph is to pull the pre-built Docker image — no\nbuild step needed.\n\nThe image is multi-arch (`linux/amd64` and `linux/arm64`) and works on macOS,\nLinux, and Windows via Docker Desktop.\n\n```bash\ndocker pull ghcr.io/evokoa/pggraph:0.1.7\ndocker run -d --rm \\\n  --name pggraph \\\n  -e POSTGRES_PASSWORD=postgres \\\n  -p 5432:5432 \\\n  ghcr.io/evokoa/pggraph:0.1.7\n```\n\nThe default database is `graph` with `pg_cron` and a maintenance job\npre-configured.\n\nVerify the extensions are loaded (uses `psql` inside the container, so you\ndon't need a local PostgreSQL client):\n\n```bash\ndocker exec pggraph psql -U postgres -d graph \\\n  -c \"SELECT extname, extversion FROM pg_extension WHERE extname IN ('graph', 'pg_cron');\"\n```\n\nIf you have `psql` installed locally you can also connect directly:\n\n```bash\npsql -h localhost -U postgres -d graph\n```\n\n## Homebrew Installation\n\nOn macOS, pgGraph is available from the\n[Evokoa Homebrew tap](https://github.com/Evokoa/homebrew-tap) for local\nPostgreSQL extension installs. The current formula is `Evokoa/tap/pggraph`,\ninstalls pgGraph 0.1.6, and builds against Homebrew `postgresql@17`.\n\n```bash\nbrew tap Evokoa/tap\nbrew install pggraph\nbrew test pggraph\n```\n\nCreate and verify the extension in a local database:\n\n```bash\nbrew services start postgresql@17\npsql -d postgres -c \"CREATE EXTENSION graph;\"\npsql -d postgres -c \"SELECT extname, extversion FROM pg_extension WHERE extname = 'graph';\"\n```\n\nIf you want the fastest zero-build quickstart, use the Docker image above. Use\nHomebrew when you want pgGraph installed as a local PostgreSQL extension on\nmacOS.\n\nTo build from source or run the full interactive demo instead, use the included\nquickstart script. It starts a disposable Docker-backed PostgreSQL database,\ninstalls pgGraph, creates two normal PostgreSQL tables, discovers the foreign\nkey relationship, builds the graph, and runs example queries.\n\nYou need Docker or Docker Desktop installed and running:\n\n- macOS: install Docker Desktop.\n- Windows: install Docker Desktop with WSL2 enabled, then run the script from\n  WSL2 or Git Bash.\n- Linux: install Docker Engine and the Docker Compose plugin.\n\n```bash\ngit clone https://github.com/evokoa/pggraph.git\ncd pggraph\n\n# run the full quickstart demo\nscripts/quickstart.sh\n\n# install into existing Postgres Docker container\nscripts/quickstart.sh docker my-postgres 17 appdb postgres\n\n# source build/install with pgrx into local PostgreSQL\nscripts/quickstart.sh pgrx\n\n# start Streamlit playground with a preset dataset and mode (csr|mutable)\nscripts/quickstart.sh playground panama csr\nscripts/quickstart.sh playground panama mutable\n```\n\nSupported modes:\n\n- `quickstart` / `demo`: build and start the Docker Postgres service, load demo\n  data, and run example graph queries. This is the default mode.\n- `setup`: build and start Postgres with pgGraph installed, but do not load the\n  sample graph.\n- `psql`: build and start Postgres, prepare demo data, then open `psql`.\n- `docker CONTAINER [PG_MAJOR] [DB_NAME] [DB_USER]`: install pgGraph into an\n  existing running Postgres Docker container via\n  `scripts/install_into_docker_postgres.sh`.\n- `pgrx [PG_MAJOR]`: build and install pgGraph into a local PostgreSQL using\n  `cargo pgrx install`.\n- `playground [panama|ldbc] [csr|mutable]`: start the Streamlit playground\n  using a preset dataset and projection mode.\n- `clean`: stop the Compose database and remove its volume.\n\nThe script works on macOS and Linux from a normal terminal, and on Windows from\nWSL2 or Git Bash with Docker Desktop. It is not a native PowerShell or Command\nPrompt script.\n\nStarting with v0.1.5, Docker release images are published for PostgreSQL 14\nthrough 18. Tags without a PostgreSQL major, such as `0.1.5` and `latest`, use\nthe default PostgreSQL 17 image.\nPostgreSQL 13 is no longer an official support target after upstream EOL, though\nthe legacy `pg13` pgrx feature remains available on a best-effort basis. The\nPostgreSQL major version of the extension package must match the target server.\n\n## PGXN Source Installation\n\npgGraph is available on PGXN as a source distribution. Because pgGraph is a\nRust/pgrx extension, building from source requires the Rust toolchain.\n\n### Prerequisites\n\n- PostgreSQL development headers and `pg_config`\n- Rust toolchain (`1.95`, pinned by `graph/rust-toolchain.toml`)\n- `cargo-pgrx` 0.18.1\n\n### Install with pgxn-client\n\n```bash\ncargo install cargo-pgrx --version 0.18.1 --locked\n# Register the installed PostgreSQL with pgrx (auto-detects the major):\nPG_MAJOR=$(pg_config --version | sed -E 's/[^0-9]*([0-9]+).*/\\1/')\ncargo pgrx init --pg${PG_MAJOR}=\"$(which pg_config)\"\npgxn install pgGraph\n```\n\n### Manual source install\n\n```bash\ngit clone https://github.com/evokoa/pggraph.git\ncd pggraph\nmake install # may need sudo\npsql -d postgres -c \"CREATE EXTENSION graph;\"\n```\n\nIf you have multiple PostgreSQL installations, set `PG_CONFIG` to the target\nserver's `pg_config`, then re-run the installation:\n\n```bash\nexport PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config\nmake install\n```\n\nIf `sudo` is needed for `make install`, preserve `PG_CONFIG`:\n\n```bash\nsudo --preserve-env=PG_CONFIG make install\n```\n\nIf compilation fails with `fatal error: postgres.h: No such file or directory`,\ninstall the PostgreSQL server development package for the target PostgreSQL\nmajor, such as `postgresql-server-dev-17` on Ubuntu or Debian.\n\n\u003e **Note:** The PGXN distribution name is `pgGraph` but the PostgreSQL extension\n\u003e name is `graph`. Use `CREATE EXTENSION graph;` after installation.\n\n## Documentation\nMore information is available in the pgGraph docs:\n\n**[Overview](https://docs.evokoa.com/pggraph/user_guide)** ·\n**[Quickstart](https://docs.evokoa.com/pggraph/quickstart)** ·\n**[Installation](https://docs.evokoa.com/pggraph/user_guide/installation)** ·\n**[Playground](https://docs.evokoa.com/pggraph/user_guide/playground)** ·\n**[Querying](https://docs.evokoa.com/pggraph/user_guide/querying)** ·\n**[SQL API](https://docs.evokoa.com/pggraph/user_guide/api-reference)**\n\n## pgGraph: High-Speed Graph Execution Inside PostgreSQL\n\npgGraph is not \"Postgres plus graph syntax.\" It is a cache-friendly graph\nexecution layer for data that already lives in your ordinary relational tables.\n\nThe core idea is simple but powerful: keep PostgreSQL as your system of record,\nbut build a highly optimized, read-heavy graph runtime from that relational\nmetadata. The result is closer to a rebuildable graph index than a graph\ndatabase: it is built from Postgres tables, operated with Postgres controls,\nand optimized for repeated bounded traversal over known topology.\n\n### The Tech: Why It's So Fast\n\nGraph traversals usually die on recursive SQL queries or endless joins. pgGraph\nbypasses this by compiling your relational data into a specialized memory\nstructure.\n\n- **O(1) adjacency via CSR.** `graph.build()` compiles your relationships into\n  forward and reverse compressed sparse row (CSR) edge stores. A node's\n  neighbors are stored as a contiguous array slice. Instead of rediscovering\n  relationships via SQL, traversals are executed as raw, graph-native memory\n  scans.\n- **A tight traversal loop.** SQL-facing calls resolve coordinates, labels,\n  filters, and tenant scopes before entering the traversal loop. Once inside,\n  the engine streams CSR neighbors, checking compact `u8` edge-label IDs,\n  typed `FilterIndex` values, tenant bitmaps, active bits, and sync overlays.\n- **Read-only artifact mapping.** Persisted `.pggraph` artifacts are written\n  atomically. When a new Postgres backend spins up, it validates the artifact\n  and maps immutable forward graph arrays and the resolution index read-only.\n  The operating system page cache can then share those physical pages across\n  isolated PostgreSQL backends without copying the base graph into each\n  backend's Rust heap. This is not a replacement for PostgreSQL's buffer pool:\n  PostgreSQL remains responsible for table storage, WAL, MVCC, durability, and\n  crash recovery, while pgGraph's artifact is derived state that can be rebuilt\n  from source tables.\n- **Predictable and safe.** Unbounded graph expansion can crash a database.\n  pgGraph includes explicit circuit breakers: depth limits, visited-node\n  tracking, frontier limits, pagination, and strict OOM/memory safeguards.\n\n### PostgreSQL Remains Authoritative\n\nYour application data does not move. Source tables, constraints, indexes, ACLs,\nRLS, backups, and app writes remain 100% standard PostgreSQL concerns.\n\npgGraph is strictly derived state. You run the algorithms over internal node\nindexes, and the engine returns source table coordinates or hydrates the raw\nPostgreSQL rows on the fly. Build, sync, vacuum, and maintenance operations are\nfully visible and SQL-callable.\n\n### How pgGraph Compares\n\n#### vs. Apache AGE: Execution Layer vs. Storage Layer\n\nApache AGE is a property graph database inside Postgres. It uses graph\nnamespaces, vertex and edge tables, `agtype`, and openCypher.\n\npgGraph does not ask you to move your data or learn Cypher. You keep your\nexisting schema and accelerate it with SQL functions like `graph.search()` and\n`graph.shortest_path()`. Use AGE for a dedicated property graph model; use\npgGraph to add bounded, high-speed graph traversal to an existing relational\nschema.\n\n#### vs. PostgreSQL 19 SQL/PGQ\n\nSQL:2023 and PostgreSQL 19 introduce `CREATE PROPERTY GRAPH`, `GRAPH_TABLE`,\nand standard graph pattern matching backed by PostgreSQL's planner and\noptimizer — the same engine that makes PostgreSQL's relational queries strong.\n\npgGraph operates at a different layer. SQL/PGQ expresses graph patterns and lets\nthe optimizer choose how to execute them. pgGraph precomputes CSR adjacency\nstores and rebuildable artifacts for workloads that repeatedly traverse the same\ntopology with bounded depth, path limits, filters, tenants, and application\npagination. The two can be complementary: future adapters could map eligible\nSQL/PGQ patterns onto pgGraph's precomputed runtime, while general graph queries\ncontinue to use PostgreSQL's relational execution path.\n\n## Community\n\npgGraph is built by [Evokoa](https://evokoa.com). \nFollow the project through\nthe links at the top of this README.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvokoa%2FpgGraph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEvokoa%2FpgGraph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEvokoa%2FpgGraph/lists"}