跳到内容
光环标志
光环基地

GraphQL

Postgres 扩展 pg_graphql,每个项目选择加入并默认禁用。启用后,它会通过专用 /graphql 路由或通用 RPC 代理公开与 REST API 相同的架构 - 继承 RLS 和角色,无需单独的 GraphQL 身份验证。

说明5分钟 读取级别 中间修改于 2026年11月11日

该页面已自动翻译。英文版具有权威性。

查询相同模式的第二种方法,而不是单独的服务#

GraphQL 由租户数据库内的 Postgres pg_graphql 扩展直接提供支持,从 SQL 表、视图和关系生成 GraphQL 架构。启用它会在与 REST API 相同的 Postgres 架构上添加第二个查询界面 - 继承完全相同的 RLS 策略和角色,无需单独的 GraphQL 服务器或身份验证层。

信息

默认情况下对所有项目禁用。 Aurabase 仅在每个项目显式选择加入时激活 pg_graphql 。有关完整查询、过滤器、游标分页和突变语法,请参阅官方 pg_graphql 文档。

/graphql 和 /rpc/graphql 上公开的 SQL 解析器#

在项目上启用 GraphQL 会在单个事务中安装 pg_graphql 并创建 "<project_schema>".graphql(query, variables, operationName, extensions)。在项目子域上,对 POST /graphql、 POST /graphql/v1、 POST /v1/graphql、 POST /v1/graphql/v1和 POST /v1/db/{project_id}/graphql (以及 POST /v1/db/{project_id}/rpc/graphql)的请求将路由到 pg_graphql 并直接返回标准 { "data": ..., "errors": ... } GraphQL JSON 负载,而不使用 REST { data, meta } 包装器。

激活周期text
ACTIVATION  ────▶  POST .../graphql/enable 或 aura 项目 graphql-enable
ENQUEUE     ────▶  作业“graphql_enable”已排队(幂等,如果已启用则无操作)
DDL         ────▶  CREATE EXTENSION pg_graphql + 包装函数 + GRANT,1 个单笔交易
FLAG        ────▶  items.graphql_enabled = true,仅在完整事务提交后设置
QUERY       ────▶  POST /graphql 或 /v1/db/{project_id}/graphql (返回原始 GraphQL JSON)
提示

激活事务是原子的:如果任何步骤(扩展、包装函数或 GRANT)失败,所有内容都会回滚并且 graphql_enabled 保持 false。

激活设置是什么#

  • 自动生成的架构。 pg_graphql 内省您的 Postgres 架构,并将每个表公开为 Relay GraphQL 类型(&lt;table&gt;Collection、 edges、 node),其中 SQL snake_case 列默认变形为 camelCase — 无需手动编写 SDL。
  • 安全调用者 — 继承 RLS。 包装器函数以调用者的权限运行 (aura_anon / aura_authenticated / aura_service_role),强制执行与 REST 请求完全相同的 RLS 策略。
  • 您可以更改并自动应用三个设置。 introspection (默认情况下关闭: { __schema { ... } } 被 Unknown field "__schema"拒绝,因此 GraphiQL 和 Apollo codegen 无法发现架构,直到您打开它), max_rows (每个集合返回的行数,1 到 10000,默认 1000)和 inflect_names (created_at → createdAt,通过默认)。 pg_graphql COMMENT ON SCHEMA … @graphql(...) 配方在项目中不起作用(您的角色不拥有架构,并且 /raw 拒绝 E'…' 文字):使用 aura projects graphql-config 或 PATCH …/graphql/config 代替,请参阅 调整设置。
  • 选择激活,幂等。 POST .../graphql/enable (控制台 JWT)或 aura projects graphql-enable --wait (CLI) 调度配置作业,并使用 --wait在 GraphQL 实际启用后返回;从来没有自动开启过。
  • 适用于所有 Postgres 层。无论您的项目运行在组织 Postgres 集群还是专用企业集群上, 都可以工作;经过验证的端到端(扩展、RLS 包装器、真实查询)。
  • 仅限 Postgres 项目。 MongoDB 项目拒绝激活 (GRAPHQL_UNSUPPORTED_ENGINE)。

激活,然后查询#

graphql-enable.shbash
# 幂等:对已启用的项目的重复调用是无操作的。
# --wait 在 GraphQL 实际启用后返回(激活是后台作业)。
aura projects graphql-enable <project_id> --wait
提示

激活以更新的项目 (graphql_enabled: true) 进行响应。注意列变形 (created_at → createdAt):请参阅 官方 pg_graphql API 参考 了解过滤器、 orderBy、光标分页 (first/after) 和突变 (insertInto<Table>Collection)。

调整设置:内省、最大行数、名称变形#

pg_graphql 从项目架构的注释中读取其设置。只有架构所有者才能编写它,因此当您提出要求时,平台会在一次事务中为您完成此操作。更改是幂等的(请求已应用的内容不会执行任何操作)并且是有界的(在任何内容排队之前,1-10000 之外的max_rows 会被拒绝)。

graphql-config.shbash
# 显示生效的设置
aura projects graphql-config <project_id>

# 打开内省(GraphiQL、graphql-codegen、Apollo),等待应用
aura projects graphql-config <project_id> --introspection on --wait

# 集合上限为 100 行并保持 SQL 名称不变
aura projects graphql-config <project_id> --max-rows 100 --inflect-names off --wait

state 讲述了有关更改的真相: pending 在应用时(使用 pending_config), failed 如果不能应用(config 中的设置仍然有效), applied 否则。必须首先启用 GraphQL(否则为GRAPHQL_NOT_ENABLED ),然后在等待答案时进行第二次更改 GRAPHQL_CONFIG_PENDING:几秒钟后重试。

内省暴露你的模式

打开 introspection 后,任何持有项目公钥的人都可以列出 GraphQL 公开的每个表和列(RLS 仍然保护行)。在开发时打开它,如果您的架构的形状很敏感,则在生产时再次关闭它。

注意事项#

命名变形和架构重新加载

默认情况下, pg_graphql 将 SQL snake_case 名称变形为 GraphQL camelCase (created_at 变为 createdAt,表 blog_posts 变为 blogPostsCollection)。 DDL 更改后,PostgREST 在几秒钟内重新加载其架构缓存,因此 /graphql 和 /rpc/graphql 都会公开更新的字段。

为了走得更远#