Supabase pg_graphql 项目中函数返回视图集时缺少主键导致的问题分析

在 Supabase 的 pg_graphql 项目中，当 PostgreSQL 函数返回一个视图集合（setof view）时，如果该视图没有定义主键，会导致 GraphQL 的 introspection 功能失败。这是一个值得开发者注意的边界情况。

问题本质

pg_graphql 扩展在生成 GraphQL Schema 时，会检查函数返回的实体是否可查询（selectable）。对于返回视图集合的函数，系统要求目标视图必须满足以下条件：

1. 视图必须对当前角色（如 authenticated 或 anon）具有查询权限
2. 视图必须定义主键（通过 @graphql 注释指令或自然主键）

当视图缺少主键定义时，虽然视图本身是可查询的，但 GraphQL 会认为其关联类型无效，从而导致函数引用失效，最终表现为 Schema 加载失败。

解决方案

开发者有两种方式解决这个问题：

方案一：为视图添加主键注释

这是推荐的做法，通过添加 @graphql 注释指令显式声明视图的主键列：

COMMENT ON VIEW view_name IS '@graphql({"primary_key_columns": ["column1", "column2"]})';

这样处理后，视图将作为常规查询对象出现在 GraphQL API 中，无需再通过函数访问。

方案二：限制函数执行权限

如果确实需要保留函数访问方式，可以撤销公共角色的执行权限：

REVOKE EXECUTE ON FUNCTION function_name FROM anon, public;

这种方式会阻止通过 API 调用这些函数，但允许服务端直接数据库连接调用。

技术背景

pg_graphql 的实现逻辑中，对函数返回类型的处理与常规表/视图有所不同。在生成 GraphQL Schema 时，系统会：

1. 检查函数返回的实体是否可查询
2. 验证实体类型是否已包含在 Schema 中
3. 对于视图，必须明确主键才能生成有效的 GraphQL 类型

这种设计确保了 GraphQL 类型系统的完整性，但也带来了这个特定的边界情况。

最佳实践

对于使用 pg_graphql 的开发者，建议：

1. 为所有需要通过 GraphQL 暴露的视图显式定义主键
2. 优先直接查询视图而非通过函数包装
3. 定期检查 Schema 生成是否正常，特别是在修改视图结构后

这个问题虽然特定，但很好地展示了 GraphQL 类型系统与关系数据库模式之间的映射挑战，理解其原理有助于更好地设计数据库和 API 结构。