pg_graphql 是由 Supabase 维护的开源 Postgres 扩展 — 它不是 Aurabase 的发明。我们构建的是其与平台的原生集成和选择性集成：每个项目都需要检查的框，而不是要提供的服务。这篇文章详细介绍了实际的架构，展示了如何启用它，并诚实地比较了 Hasura 和 PostGraphile v5 的权衡。
pg_graphql在 Postgres 中作为 SQL 扩展运行——与 Hasura 和 PostGraphile 不同，无需部署单独的 GraphQL 服务器。- Aurabase 提供的包装函数是
SECURITY INVOKER：您的 RLS 策略自动应用，无需并行维护第二个权限系统。 - 仅针对每个项目选择激活 —
aura projects graphql-enable或 Studio — 默认情况下不会在任何项目上激活。 - Hasura 于 2025 年 6 月正式重新将重点放在 PromptQL 和 AI 代理上，但没有放弃其 GraphQL 引擎。
- PostGraphile v5 于 2026 年 3 月 24 日全面上市——是一个直接且活跃的竞争对手，而不是一个休眠项目。
pg_graphql，一句话
pg_graphql 内省您的 SQL 模式并生成符合 Relay 约定的 GraphQL 模式 — <table>Collection、 edges、 node、按列类型过滤、按游标分页。无需手动编写或维护 SDL：GraphQL 架构遵循 Postgres 架构。
对于架构来说重要的一点是：这个模式生成器位于数据库内部，作为 SQL 函数，而不是作为旁边的 HTTP 进程。 Aurabase 将 1.6.1 版本的扩展（于 2026 年 5 月 7 日发布）固定在其 Postgres 映像 中 — 与 Supabase 分发的官方 .deb 软件包相同。它安装在共享集群和专用 Postgres 实例上。
如果您来自 Supabase，那里 pg_graphql 已经本地启用了很长时间，您会熟悉其中的逻辑。我们详细的 比较 和我们的 迁移指南 涵盖了 RLS 架构和策略的其余部分，它们保持不变。
Hasura 和 PostGraphile 发生了什么变化
“Postgres 上的即时 GraphQL”的两个历史竞争对手都没有消失。他们的定位已经发生了变化，更新的文章应该反映这一点，而不是引用两年前的状态。
Hasura 于 2025 年 6 月发表了一篇文章，标题明确为 “从 GraphQL 到 PromptQL：新篇章开始”，由其联合创始人 Tanmai Gopal 签名。传达的信息是：该公司正在将其路线图重新集中在 PromptQL上，这是一个专为人工智能代理设计的数据访问层。 GraphQL 引擎并未被删除——Hasura 的主页仍然将其显示为“经过考验”——但它不再是优先消息。
PostGraphile则相反。其版本 5 自 2023 年以来以 Beta 形式开发，并于 2026 年 3 月 24 日全面发布，并配备了名为 Grafast 的新查询计划引擎。这并不是一个即将失去动力的项目：最后一个版本 5.1.4 的日期是 2026 年 8 月 5 日。仅在 2026 年 8 月 16 日至 22 日这一周，npm 软件包 的下载量就达到了 119,230 次（npm 注册表，2026 年 8 月 23 日查阅）。
实际后果：真正的空闲空间不是“Postgres 上的 GraphQL，没有人触及它”——而是特定的 GraphQL 零配置槽，通过一个命令激活，没有托管服务。哈苏拉通过战略选择远离它； PostGraphile 从未针对过它，它的模型仍然是“自行集成 Node.js 库”。
每个解决方案实际转向的地方
构成其他一切（运营成本、攻击面、延迟）的差异在于 GraphQL 引擎的运行位置。
| 转向何处 | SQL 扩展，在 Postgres 中 | 单独的 GraphQL 服务器 (Go)，位于 Postgres 前面 | Node.js 库/服务器，领先于 Postgres |
|---|---|---|---|
| 需要部署 | 无 — 由项目标志激活 | 是的 — 托管并扩展 Hasura 引擎 | 是的 - 托管 Node 进程或将其与您的服务器集成 |
| 权限模型 | 旧版 Postgres RLS（安全调用者） | Hasura 自己的权限系统，每个角色/表 | RLS Postgres 通过 pgSettings — 也是本机委托 |
| 默认自省 | 残疾人 | 取决于发动机配置 | 取决于服务器配置 |
| 定位2026 | Postgres BaaS 的本机选项 | 自 2025 年 6 月起重新关注 PromptQL/IA | GA v5 自 2026 年 3 月起，活跃项目 |
| 光环基地 | 哈苏拉 | 后记V5 |
老实说：PostGraphile 还通过 pgSettings 和角色切换将授权委托给 Postgres — 原生 RLS 并不是 pg_graphql 独有的。仍然不同的是谁托管和配置这个桥：在 PostGraphile 是你；在 PostGraphile 是你；在在 Aurabase，这已经完成了。
Aurabase 如何在项目上激活 pg_graphql
激活是按项目选择加入的，并为 Postgres 引擎项目保留 — MongoDB 项目拒绝请求 (GRAPHQL_UNSUPPORTED_ENGINE)，pg_graphql 是 Postgres 扩展，在其他引擎上没有等效项。
通过 CLI 或直接调用管理计划：
在服务器端，调用执行配置程序在单个事务中执行的 graphql_enable 作业：安装扩展、在架构中创建 graphql() 函数、授予应用程序角色。如果某个步骤失败，一切都会被取消 - 永远不会半途安装包装器，并且 graphql_enabled 仅在完全成功后才会移动到 true。
它既可以在共享的 Postgres 集群上运行，也可以在每个项目的专用 CNPG 实例上运行 - 两个不同的 Postgres 映像，但具有相同的扩展机制。在专用实例上，扩展是通过 CNPG 运算符的声明性清单安装的，而不是直接 SQL — 这是最近的更正。专用集群无需应用程序超级用户访问权限即可运行，而 pg_graphql 的 CREATE EXTENSION恰恰需要此权限。
在 Studio 中，相同的流程经过“表配置”选项卡。那里的按钮可以激活项目级别的扩展 - 与上面相同的 HTTP 调用，轮询直到收敛。然后，第二个控件为每个表设置一个 @graphql 指令，以激活或不激活 totalCount 及其 GraphQL 集合上的聚合字段，而无需离开编辑器。
单个命令视图：激活 → 配置作业线程化（幂等，如果已在运行则无操作）→ DDL 事务（扩展、包装函数、GRANT）→ 仅在完全成功后设置标志 graphql_enabled → 可以通过 /rpc/graphql请求。
旧版 RLS，无需维护第二个系统
Aurabase 设置的函数是 SECURITY INVOKER — Postgres 的默认行为，经过解释，以便将来的重构不会意外更改它。它以实际调用者的权限运行（aura_anon、 aura_authenticated 或 aura_service_role，具体取决于 JWT 声明），因此您的 RLS 策略 完全适用于 REST 请求。
SECURITY DEFINER 函数将绕过整个 RLS — 内部检查：在超级用户连接下调用 graphql.resolve 而不更改应用程序角色会返回所有所有者的行，无论是否为 RLS。这种选择正是避免了跨租户风险。
在 Hasura，架构在构造上有所不同：引擎将每个 GraphQL 查询转换为受 Hasura 特定权限规则约束的 SQL 查询。这些规则是在其自己的层中为每个角色和每个表定义的——Postgres RLS 的并行系统，而不是其委托。审计访问规则的地方有两个，而不是只有一个。
默认情况下，每个 Aurabase 项目上的自省 ({ __schema { ... } }) 保持禁用状态 — 这种状态与平台的其他部分一致。如果 Apollo Studio 或 graphql-codegen 等工具需要它，它可以通过 COMMENT ON SCHEMA 由模式激活。
启用然后查询您的 GraphQL API
一旦 graphql_enabled 到 true，网关上就不会出现专用的 /graphql 路由。该请求通过通用 RPC 代理，就像从 SDK 调用的任何 Postgres 函数一样。
响应遵循 GraphQL 规范 — { data, errors } — 无需额外的 Aurabase 包装：网关检测到目标 RPC 是 graphql 并且不会重新包装它，这与普通 RPC 不同。标准 GraphQL 客户端（Apollo、urql、graphql-request）按原样使用输出。
激活时默认设置两个设置，通过图中的 @graphql 指令： max_rows: 1000 和 inflect_names: true。 pg_graphql 默认情况下每个集合的上限为 10,000 行 — 如果没有 first:，大表可能会导致内存饱和。 inflect_names 提供可读的类型名称，而不是 SQL 表的原始 Snake_case。
pg_graphql 还没有做什么
本着本博客的精神，要记录而不是隐藏。
- 没有本机 GraphQL 订阅。 pg_graphql 涵盖查询和突变，而不是实时
subscriptions— 这是扩展本身的限制，而不是 Aurabase 的遗漏。实时 Aurabase 存在，但通过单独的通道 (postgres_changes)，而不是 GraphQL 订阅桥。 - 没有 Hasura 那样的声明性操作。 “连接到 GraphQL 突变的业务 Webhook”模型没有直接等效项 - 在 Aurabase 上，此逻辑通过 Postgres 函数或 Edge 函数，而不是通过专用的 GraphQL 配置。
- 为 Postgres 引擎保留。 MongoDB 项目无法启用此功能 — 无意解决此问题。
为什么激活仍然是选择加入而不是默认激活：租户数据库的 GRANT/Roles 区域有记录的回归历史记录。这足以证明，在考虑更广泛的缺陷之前，如果没有逐个项目的明确验证，任何功能都不会触及它。
Aurabase、Hasura 或 PostGraphile：取决于您的上下文
所有三个选项都是合理的 - 正确的选择取决于您已经拥有的以及您希望避免的。
- Aurabase 上的 pg_graphql — 如果您的 RLS 数据库和策略已存在于 Aurabase 上，并且您希望采用第二种方式来查询它，而无需监视其他服务。
- Hasura — 如果您在单个 GraphQL 模式后面联合多个数据源（不仅仅是 Postgres），或者 PromptQL 及其 AI 代理方法适合您的路线图。
- PostGraphile v5 — 如果您想精细控制通过其插件系统生成的模式，并且您已经运行了一个 Node.js 服务器来集成它。
有关完整查询语法 - 按列类型过滤、orderBy排序、按游标分页、insertInto<Table>Collection 突变 - 请参阅官方 pg_graphql文档。下面的 Aurabase GraphQL 文档也详细介绍了整个周期。