pgGraph Banner

pgGraph pgGraph documentation

为你现有的 Postgres 数据带来图数据库级能力。

GitHub stars Version 0.1.4 License: Apache-2.0 PostgreSQL 14-18

GitHub issues GitHub pull requests Last commit

Built by Evokoa Follow on X Join the Evokoa Discord Follow on Product Hunt

pgGraph 是一个 PostgreSQL 扩展，用于直接针对普通 PostgreSQL 表运行图搜索、遍历、最短路径和关系查询。 你的表仍然是事实来源。pgGraph 会构建一个派生的图索引，并让你通过 SQL 使用 `graph` schema 中的函数来查询它。 > [!IMPORTANT] > pgGraph 处于早期 alpha 阶段。虽然内部测试表明它已相当稳定，但目前请避免在生产环境中使用；建议在 Docker 或专用开发数据库中尝试它，并分享反馈来帮助我们改进项目。 ## 为什么选择 pgGraph？ PostgreSQL 很擅长关系查询，但基于图结构的查询通常需要为每个 schema 编写自定义递归 SQL： - “查找 Alice 在 2 跳以内相关的记录。” - “查找这个人与这家公司之间的最短路径。” - “在已注册的表中搜索节点。” pgGraph 在你现有的 PostgreSQL 表之上添加图查询，不需要单独的图数据库、图专用存储系统或新的查询语言。 ## 快速开始 想要快速体验 pgGraph，最简单的方法是运行提供的快速启动脚本。 它会启动一个一次性的、基于 Docker 的 PostgreSQL 数据库，安装 pgGraph，创建两个普通 PostgreSQL 表，发现外键关系，构建图，并运行示例查询。 你需要安装并运行 Docker 或 Docker Desktop： - macOS：安装 Docker Desktop。 - Windows：安装启用了 WSL2 的 Docker Desktop，然后从 WSL2 或 Git Bash 运行脚本。 - Linux：安装 Docker Engine 和 Docker Compose 插件。 ```bash git clone https://github.com/evokoa/pggraph.git cd pggraph # 运行完整的快速开始演示 scripts/quickstart.sh # 安装到现有的 Postgres Docker 容器 scripts/quickstart.sh docker my-postgres 17 appdb postgres # 使用 pgrx 从源码构建并安装到本地 PostgreSQL scripts/quickstart.sh pgrx # 使用预设数据集启动 Streamlit playground（panama|ldbc） scripts/quickstart.sh playground panama ``` 支持的模式： - `quickstart` / `demo`：构建并启动 Docker Postgres 服务，加载演示数据， 并运行示例图查询。这是默认模式。 - `setup`：构建并启动已安装 pgGraph 的 Postgres，但不加载示例图。 - `psql`：构建并启动 Postgres，准备演示数据，然后打开 `psql`。 - `docker CONTAINER [PG_MAJOR] [DB_NAME] [DB_USER]`：通过 `scripts/install_into_docker_postgres.sh` 将 pgGraph 安装到现有运行中的 Postgres Docker 容器。 - `pgrx [PG_MAJOR]`：使用 `cargo pgrx install` 构建 pgGraph，并安装到本地 PostgreSQL。 - `playground [panama|ldbc]`：使用预设数据集启动 Streamlit playground。 - `clean`：停止 Compose 数据库并删除其 volume。 该脚本可在 macOS 和 Linux 的普通终端中运行，也可在 Windows 上通过 WSL2 或带有 Docker Desktop 的 Git Bash 运行。它不是原生 PowerShell 或命令提示符脚本。 基础 Docker 镜像目前运行 PostgreSQL 17。打包脚本可以为官方支持的 PostgreSQL 14 到 18 目标构建扩展构建产物。PostgreSQL 13 已到上游 EOL，不再是官方支持目标，但旧的 `pg13` pgrx feature 仍可按 best-effort 方式使用。扩展的 PostgreSQL 主版本必须与目标服务器匹配。 ## PGXN 源码安装 pgGraph 在 PGXN 上以源码分发包的形式提供。因为 pgGraph 是一个 Rust/pgrx 扩展， 从源码构建需要 Rust 工具链。 ### 前置要求 - PostgreSQL 开发头文件和 `pg_config` - Rust 工具链（`1.95`，由 `graph/rust-toolchain.toml` 锁定） - `cargo-pgrx` 0.18.0 ### 使用 pgxn-client 安装 ```bash cargo install cargo-pgrx --version 0.18.0 --locked # 用 pgrx 注册已安装的 PostgreSQL（自动识别主版本）： 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 ``` ### 手动源码安装 ```bash git clone https://github.com/evokoa/pggraph.git cd pggraph make install # 可能需要 sudo psql -d postgres -c "CREATE EXTENSION graph;" ``` 如果你安装了多个 PostgreSQL 版本，可以将 `PG_CONFIG` 指向目标服务器的 `pg_config`，然后重新运行安装： ```bash export PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config make install ``` 如果 `make install` 需要 `sudo`，请保留 `PG_CONFIG` 环境变量： ```bash sudo --preserve-env=PG_CONFIG make install ``` 如果编译失败并出现 `fatal error: postgres.h: No such file or directory`， 请安装目标 PostgreSQL 主版本对应的服务器开发包，例如 Ubuntu 或 Debian 上的 `postgresql-server-dev-17`。 > **注意：** PGXN 分发名称是 `pgGraph`，但 PostgreSQL 扩展名是 `graph`。 > 安装后请使用 `CREATE EXTENSION graph;`。 ## 文档 更多信息可在 pgGraph 文档中找到： **[概览](https://docs.evokoa.com/pggraph/user_guide)** · **[快速开始](https://docs.evokoa.com/pggraph/quickstart)** · **[安装](https://docs.evokoa.com/pggraph/user_guide/installation)** · **[Playground](https://docs.evokoa.com/pggraph/user_guide/playground)** · **[查询](https://docs.evokoa.com/pggraph/user_guide/querying)** · **[SQL API](https://docs.evokoa.com/pggraph/user_guide/api-reference)** ## pgGraph：PostgreSQL 内部的高速图执行 pgGraph 不是“Postgres 加上图语法”。它是一个缓存友好的图执行层，用于已经存在于普通关系表中的数据。 核心思想简单但强大：保留 PostgreSQL 作为你的核心记录系统，但从这些关系元数据构建一个针对读取优化的图运行时。结果更接近可重建的图索引而不是图数据库：它从 Postgres 表构建，受 Postgres 权限系统控制，并针对已知拓扑上的重复、有边界遍历进行优化。 ### 技术：为什么它这么快 图遍历通常会卡在递归 SQL 查询或无尽的 join 上。pgGraph 通过把你的关系数据编译成专门的内存结构来绕过这一点。 - **通过 CSR 实现 O(1) 邻接访问。** `graph.build()` 会把你的关系编译成正向和反向的压缩稀疏行（CSR）边存储。一个节点的邻居被存储为连续的数组切片。遍历不是通过 SQL 重新发现关系，而是作为底层的、图原生的内存扫描来执行。 - **紧凑的遍历热循环。** 面向 SQL 的调用会在进入遍历循环之前解析坐标、标签、过滤器和租户范围。一旦进入内部，引擎会流式读取 CSR 邻居，检查紧凑的 `u8` 边标签 ID、有类型的 `FilterIndex` 值、租户位图、活跃位和同步覆盖层。 - **只读构件映射。** 持久化的 `.pggraph` 文件会被原子写入。当一个新的 Postgres 后端进程启动时，它会验证该构件，并以只读方式映射不可变的正向图数组和解析索引。操作系统页缓存可以在相互隔离的 PostgreSQL 后端进程之间共享这些物理页，而无需把基础图复制到每个后端的 Rust 堆中。这不是 PostgreSQL buffer pool 的替代品：PostgreSQL 仍然负责表存储、WAL、MVCC、持久性和崩溃恢复；pgGraph 的构件是可从源表重建的派生状态。 - **可预测且安全。** 无限制的图遍历可能让数据库崩溃。pgGraph 包含显式断路器：深度限制、已访问节点跟踪、frontier 限制、分页，以及严格的 OOM/内存保护。 ### PostgreSQL 仍然权威 你的应用数据不会移动。源表、约束、索引、ACL、RLS、备份和应用写入仍然 100% 是标准 PostgreSQL 的原生特性。 pgGraph 的状态是严格派生自原始数据的。你在内部节点索引上运行算法，引擎返回源表坐标，或即时补全原始 PostgreSQL 行。构建、同步、vacuum 和维护操作都是完全可见且可通过 SQL 调用的。 ### pgGraph 如何比较 #### 对比 Apache AGE：执行层 vs. 存储层 Apache AGE 是 Postgres 内部的属性图数据库。它使用图命名空间、顶点和边表、`agtype` 以及 openCypher。 pgGraph 不要求你移动数据或学习 Cypher。你保留现有 schema，并用 `graph.search()` 和 `graph.shortest_path()` 这样的 SQL 函数加速它。对于专用的属性图模型，请使用 AGE；对于给现有关系 schema 添加有边界的高速图遍历，请使用 pgGraph。 #### 对比 PostgreSQL 19 SQL/PGQ SQL:2023 和 PostgreSQL 19 引入了 `CREATE PROPERTY GRAPH`、`GRAPH_TABLE` 和标准图模式匹配，并由 PostgreSQL 的 planner 和 optimizer 支撑——与驱动 PostgreSQL 强大关系查询的引擎相同。 pgGraph 在不同的层级上工作。SQL/PGQ 表达图模式并让 optimizer 选择执行方式。pgGraph 为反复遍历同一拓扑的工作负载预计算 CSR 邻接存储和可重建构件，适合有深度上限、路径限制、过滤器、租户范围和应用分页的遍历。两者可以互补：未来的适配器可以把符合条件的 SQL/PGQ 模式映射到 pgGraph 的预计算运行时，而通用图查询继续使用 PostgreSQL 的关系执行路径。 ## 社区 pgGraph 由 [Evokoa](https://evokoa.com) 构建。 通过本 README 顶部的链接关注该项目。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。