Graphile Build PG 详解:从 PostgreSQL 内省到高性能 GraphQL Schema 的自动生成
Graphile Build PG 详解:从 PostgreSQL 内省到高性能 GraphQL Schema 的自动生成
导读
graphile-build-pg 是 Graphile Build 体系中的一组 PostgreSQL 插件集合,它以数据库中的表、视图、函数等资源为输入,通过 pg-introspection 内省数据库,再基于 @dataplan/pg 构建由 codec、resource、relation 组成的 registry,最终由插件体系自动生成 GraphQL 类型、字段与 Grafast plan resolver 函数,输出"高性能、强大、自动生成却又高度灵活"的 GraphQL Schema。阅读本文后,你将掌握 graphile-build-pg 的三层生成链路、插件与预设的组织方式、registry 的手动构建替代方案,以及它如何借助 Grafast 查询计划规避 N+1 查询问题。
一、graphile-build-pg 是什么
graphile-build-pg 是 graphile-build 插件体系的 PostgreSQL 扩展,本质上是一组 graphile-build 插件(plugin)的集合,这些插件为你的 GraphQL schema 补充基于 PostgreSQL 数据库中表(tables)、视图(views)、函数(functions)以及其他资源(resources)的 GraphQL 类型与字段。
它当前仓库中的版本为 5.1.3(见 package.json),在 monorepo 中与 @dataplan/pg、grafast、graphile-build、graphile-config、pg-sql2 等互为 peer 依赖,运行环境要求 Node.js >=22。
从入口文件可以看到,该包对外导出了数十个插件、defaultPreset 预设、parseDatabaseIdentifier / parseDatabaseIdentifiers 工具函数,以及 withPgClientFromPgService、getWithPgClientFromPgService、sql 等来自 @dataplan/pg 与 pg-sql2 的透传导出。也就是说,接入 graphile-build-pg 时,你通常无需再单独引入 @dataplan/pg 与 pg-sql2,它们会随该包一起可用。
二、核心工作链路:内省 → Registry → GraphQL Schema
graphile-build-pg 的整个工作过程可以拆解为三个相互衔接的阶段,这是理解该包的核心骨架:
- 数据库内省(Introspection):使用
pg-introspection对 PostgreSQL 数据库发起内省查询,把数据库的命名空间、类(表/视图)、属性、约束、过程/函数、角色、类型、枚举、扩展、索引、语言、范围、依赖与注释等实体抽取为结构化数据。 - 构建 Registry(@dataplan/pg registry):基于内省结果构建一个由 codecs(编码器)、resources(资源)、relations(关系) 组成的 registry,供后续 schema 生成阶段消费。
- 生成 GraphQL Schema:graphile-build-pg 的插件检查 registry,创建对应的 GraphQL 类型、字段,以及 Grafast 的 plan resolver 函数。
2.1 阶段一:PgIntrospectionPlugin 负责内省
PgIntrospectionPlugin 是内省阶段的执行者,其描述为"Introspects PostgreSQL databases and makes the results available to other plugins"。它的关键设计包括:
- 通过
gatherConfig注册命名空间pgIntrospection,向其他插件暴露getIntrospection()、getService()、getExecutorForService()、getClass()、getProc()、getType()等一系列 helpers; - 对 preset 中配置的每个
pgServices依次执行makeIntrospectionQuery(),再用parseIntrospectionResults()把内省文本解析成结构化结果; - 内省结果解析完成后,会按实体类型(namespace、class、attribute、constraint、proc、role、type、enum、extension、index、language、range、depend、description)逐一触发
pgIntrospection_*事件(hook),供其他插件订阅消费; - 插件声明
before: ["PgRegistryPlugin"],确保内省在 registry 构建之前完成; - 同时为每个 pgService 创建
PgExecutor实例,并在pgRegistry_PgRegistryBuilder_pgExecutors钩子中将 executor 注册进 registry builder; - 它还在
watch阶段订阅postgraphile_watch频道,配合数据库中的 watch fixtures(默认通过installWatchFixtures: true尝试以超级用户连接安装),实现 schema 的自动热重载(watch 模式)。
2.2 阶段二:PgRegistryPlugin 组装 Registry
PgRegistryPlugin 负责在 gather 阶段生成 registry,其描述为"Generates the registry during the gather phase, containing details of all the codecs, resources, relations and behaviors."
它通过 makeRegistryBuilder() 创建 registry builder,然后按固定顺序依次触发五个构建事件:
pgRegistry_PgRegistryBuilder_init(初始化,PgIntrospectionPlugin 在此触发内省)pgRegistry_PgRegistryBuilder_pgExecutors(注册各 pgService 对应的 executor)pgRegistry_PgRegistryBuilder_pgCodecs(注册 codecs)pgRegistry_PgRegistryBuilder_pgResources(注册 resources)pgRegistry_PgRegistryBuilder_pgRelations(注册 relations)pgRegistry_PgRegistryBuilder_finalize(收尾)
最终调用 registryBuilder.build() 得到 PgRegistry,再触发 pgRegistry_PgRegistry 事件,并把结果写入 gather 输出 output.pgRegistry,作为 BuildInput.pgRegistry 供 schema 生成阶段使用。
2.3 阶段三:插件群检查 Registry 生成 Schema
registry 就绪后,剩余的 schema 阶段插件开始工作。这些插件各自聚焦一个功能面,例如:
- PgCodecsPlugin:为数据库中的类型构建 codec(
recordCodec、enumCodec、listOfCodec、rangeOfCodec、domainOfCodec等),并在 Build 上下文中暴露getPgCodecByDatabaseName(); - PgTypesPlugin:为一批标准 PostgreSQL 类型注册对应的 GraphQL 类型(如
pgUseCustomNetworkScalars可控制网络类型标量的使用); - PgTablesPlugin:把每个表/视图映射为一个
PgResource,并注入table、resource:select、resource:insert、resource:update、resource:delete等 behavior 字符串; - PgRelationsPlugin:创建
@dataplan/pgresource 之间的关联,并把关联镜像到 GraphQL schema(它声明after: ["smart-tags", "PgFakeConstraintsPlugin", "PgTablesPlugin"])。
三、插件体系与 defaultPreset
graphile-build-pg 通过 preset.ts 提供了开箱即用的预设:
GraphileBuildPgLibPreset:把@dataplan/pg、@dataplan/json、pg-sql2及各自的版本号注入lib,使得插件内可直接使用这些库;defaultPreset:继承GraphileBuildPgLibPreset,并注册一套完整的插件序列。
defaultPreset 中注册的插件完整清单(与入口文件的导出一一对应)包括:
| 插件 | 职责 |
|---|---|
PgBasicsPlugin |
提供最基础的 schema 行为与约定 |
PgLtreePlugin |
对 ltree 类型提供支持 |
PgEnumDomainsPlugin / PgEnumTablesPlugin |
把 PostgreSQL domain 枚举与枚举表映射为 GraphQL 枚举 |
PgCodecsPlugin |
构建 codec 注册表 |
PgContextPlugin |
引入 PgContext(来自 @dataplan/pg) |
PgTypesPlugin |
注册标准 PostgreSQL 类型的 GraphQL 类型 |
PgRefsPlugin / PgRelationsPlugin |
构建 refs 与 relations |
PgIntrospectionPlugin |
数据库内省 |
PgTablesPlugin |
表/视图 → resource 映射 |
PgMutationCreatePlugin / PgMutationUpdateDeletePlugin / PgMutationPayloadEdgePlugin |
生成 CRUD 变更(create、update/delete、payload edge) |
PgProceduresPlugin |
把数据库函数/过程暴露为 GraphQL 字段 |
PgAttributesPlugin |
把列属性映射为对象字段 |
PgNodeIdAttributesPlugin |
处理 Node 的 id 编码 |
PgAllRowsPlugin / PgRowByUniquePlugin |
根级集合查询与按唯一键取单行 |
PgConnectionTotalCountPlugin |
connection 上的 totalCount |
PgAttributeDeprecationPlugin |
基于注释的字段弃用 |
PgCustomTypeFieldPlugin |
自定义类型字段 |
PgFirstLastBeforeAfterArgsPlugin |
first/last/before/after 分页参数 |
PgConnectionArgOrderByPlugin / PgOrderByPrimaryKeyPlugin / PgOrderAllAttributesPlugin / PgOrderCustomFieldsPlugin / PgConnectionArgOrderByDefaultValuePlugin |
orderBy 体系(连接参数、主键排序、全属性排序、自定义排序、默认排序值) |
PgConditionArgumentPlugin / PgConditionCustomFieldsPlugin |
condition(过滤)参数与自定义过滤字段 |
PgFakeConstraintsPlugin |
基于唯一索引模拟约束,用于关联推导 |
PgTableNodePlugin |
把表映射为 Relay Node 类型 |
PgJWTPlugin |
JWT 相关的类型与字段支持 |
PgRemoveExtensionResourcesPlugin |
移除扩展引入的冗余资源 |
PgPolymorphismPlugin / PgPolymorphismOnlyArgumentPlugin / PgInterfaceModeUnionAllRowsPlugin |
多态/接口模式支持 |
PgRBACPlugin |
基于数据库角色/权限的行为过滤 |
PgIndexBehaviorsPlugin |
基于索引的行为推断 |
PgRegistryPlugin / PgRegistryReductionPlugin |
registry 构建与精简 |
实际使用中,你既可以直接 extends 这个 defaultPreset,也可以挑选其中部分插件自由组合,这正是 graphile-build-pg "自动生成却又高度灵活"的体现。
四、Registry 三要素:Codecs、Resources、Relations
@dataplan/pg 的 registry 由三类核心实体构成,graphile-build-pg 的插件围绕它们展开:
- Codec(编码器):描述一种 PostgreSQL 类型如何被解码/编码,例如
recordCodec描述一个表/复合类型行的结构(每个属性对应一个列、一个子 codec 与notNull标记),enumCodec描述枚举,TYPES提供内置标量类型集合。graphile-build-pg 在类型声明中为 codec 补充了name、behavior、deprecated、implements、interface、unionMember、nodeIdCodec等 smart tags。 - Resource(资源):表示"获取某 codec 类型若干值的一种方式"。它不一定是表本身,也可能是返回记录的函数,或表的子集(如
admin_users可能是users where admin is true)。PgResource携带 executor、SQL 片段(from)、唯一键(uniques)、参数(parameters)等信息。 - Relation(关系):描述两个 codec/resource 之间的关联(如外键关系、计算关联),graphile-build-pg 会把它们镜像为 GraphQL schema 中的单值字段或连接/列表字段。
在 GraphileBuild.PgResourceTags(见类型声明)中,resource 支持 fieldName、resultFieldName、behavior、primaryKey、foreignKey、unique、deprecated、nodeIdCodec、returnType、enum、partitionExpose 等标签,这些标签既可由数据库中的 smart comments 注入,也可在手动构建 registry 时直接写在 extensions.tags 里。
五、替代方案:手动构建 Registry(跳过内省)
原文档明确指出:如果你不想用数据库内省结果来生成 schema,可以自行构建 registry,从而对"进入 GraphQL API 的内容"拥有完全控制权,同时仍比完全手写 schema 节省大量工作。
仓库中的示例 NO_DATA_GATHERING.ts 完整演示了这一路径,其要点如下:
- 用
makePgAdaptorWithPgClient(pool)提供数据库客户端访问; - 用
recordCodec()手工定义app_public.users、app_public.forums、app_public.messages等 codec,为每个属性指定子 codec 与notNull,并通过extensions.tags.name指定命名; - 用
pgResourceOptions()定义表资源与函数资源(例如把返回标量的unique_author_count函数声明为 resource,并借助sqlFromArgDigests(args)把参数安全地拼进 SQL 片段); - 用
makeRegistryBuilder().addResource(...).addRelation(...)把 resources 与 relations(如messages.author、messages.forum)组装为PgRegistry; - 最后把 registry 作为
BuildInput.pgRegistry传给buildSchema(config, input)。
这里有两个要点值得说明:
- 纯手动 registry 可以不经过 gather 阶段,即"NO_DATA_GATHERING"的含义——内省/注册由用户代码完成,schema 构建插件只负责把 registry 映射为 GraphQL 类型与字段;
- 示例中还演示了
exportSchema()(来自graphile-export)把运行时 schema 导出为可静态加载的 JS 模块,并再次执行相同查询验证导出结果,说明这类 schema 具备良好的可移植性。
六、实际接入配置示例
仓库的配置示例展示了接入 graphile-build-pg 的最小化配置骨架:
import "graphile-config";
import { getWithPgClientFromPgService } from "@dataplan/pg";
import { makePgService } from "@dataplan/pg/adaptors/pg";
import {
defaultPreset as graphileBuildPreset,
QueryQueryPlugin,
SwallowErrorsPlugin,
} from "graphile-build";
import { Pool } from "pg";
import { defaultPreset as graphileBuildPgPreset } from "graphile-build-pg";
const DATABASE_CONNECTION_STRING = "postgres:///pagila";
const DATABASE_SCHEMAS: string[] = ["public", "app_public"];
export function getPool() {
const pool = new Pool({ connectionString: DATABASE_CONNECTION_STRING });
pool.on("error", (e) => console.log("Client error", e));
return pool;
}
export async function makeSharedPresetAndClient(pool: Pool) {
const preset: GraphileConfig.Preset = {
extends: [graphileBuildPreset, graphileBuildPgPreset],
plugins: [QueryQueryPlugin, SwallowErrorsPlugin],
pgServices: [
makePgService({
name: "main",
schemas: DATABASE_SCHEMAS,
pgSettingsKey: "pgSettings",
withPgClientKey: "withPgClient",
pool,
}),
],
gather: {
// pgJwtTypes: "jwt_token",
},
schema: {
// pgJwtSecret: "secret",
},
};
const withPgClient = await getWithPgClientFromPgService(
preset.pgServices![0]!,
);
return { preset, withPgClient };
}
配置要点:
extends: [graphileBuildPreset, graphileBuildPgPreset]:同时继承 graphile-build 与 graphile-build-pg 的默认预设,这是最小可运行组合;pgServices:声明要内省的数据库服务。makePgService()接受name(服务名,默认main)、schemas(要暴露的 schema 列表)、pgSettingsKey/withPgClientKey(在 GraphQL context 中读取 pgSettings 与数据库客户端的键名)、pool(连接池)等参数。注意:多个 pgService 之间name、withPgClientKey、pgSettingsKey均不允许重复,否则内省阶段会直接抛错(见 PgIntrospectionPlugin 的校验逻辑);gather/schema中的pgJwtTypes、pgJwtSecret等选项配合PgJWTPlugin使用;- 示例中还演示了自定义
EnumManglingPlugin通过inflection.replace重写enumValue,把枚举值规范化以兼容 GraphQL 命名规范——这体现了"高度灵活"的可扩展性。
七、性能优势:查询计划与 N+1 问题
原文档特别强调了 graphile-build-pg 的核心性能卖点:得益于 Grafast 的查询计划(query planning)能力,本包的插件不会表现出许多基于数据库的 GraphQL API 常见的 N+1 查询问题;对于除最扁平查询以外的绝大多数 GraphQL 查询,这些插件通常显著优于基于 DataLoader 的方案——且 GraphQL 查询越复杂,收益越大。
其底层原理与 Grafast 的执行模型直接相关:graphile-build-pg 生成的 plan resolver 函数并不直接逐字段发 SQL,而是把整个查询解析为 step 依赖图,再由 @dataplan/pg 的 executor 统一生成 SQL 并批量执行(例如 PgExecutor 依据 registry 中 codec/resource 的元数据,把多个关联字段合并进同一批查询)。这也是为什么"内省 + registry"这种中间抽象如此重要——它让 schema 生成与 SQL 执行解耦,前者关注类型/字段的形状,后者关注查询的合并与参数化。
值得说明的是,这一结论的适用前提是:查询经由 graphile-build-pg 生成的 plan resolver 执行(即默认路径);如果你在 schema 中手写绕过 plan 的 resolver,则需自行保证查询合并策略。
八、在 PostGraphile 中的角色
graphile-build-pg 是 PostGraphile 的核心组件。PostGraphile 借助它以最小开发成本构建"理想、性能出色、遵循最佳实践、以 PostgreSQL 为主要后端"的 GraphQL API。从仓库结构看,PostGraphile 的 postgraphile 包直接依赖 @dataplan/pg、grafast、grafserv、pg-sql2 等(见 postgraphile/postgraphile/package.json),而 graphile-build-pg 则承载了其中"数据库 → GraphQL schema"这一关键转化。换言之,如果你只需要一个面向单库、快速上手的 GraphQL API 服务,直接使用 PostGraphile 即可;如果需要更精细地控制 schema 生成过程、自定义插件与 inflection,则可以像上文一样直接基于 graphile-build-pg 的预设与插件组合来构建。
九、小结与延伸阅读
总结而言,graphile-build-pg 的价值在于把"数据库建模"与"GraphQL API 设计"之间的鸿沟压缩到极致:
- 自动:内省数据库即可获得完整的 CRUD、查询、排序、过滤、分页、关系与函数能力;
- 高性能:经由 Grafast 查询计划避免 N+1,复杂度越高收益越大;
- 可掌控:可自定义插件、inflection、smart tags,也可完全跳过内省、手写 registry。
进一步深入本仓库时,推荐按以下路径阅读:
- 插件清单与类型标签:src/index.ts
- 默认预设与插件装配:src/preset.ts
- 内省实现:src/plugins/PgIntrospectionPlugin.ts
- registry 构建:src/plugins/PgRegistryPlugin.ts
- 手动构建 registry 示例:src/examples/NO_DATA_GATHERING.ts
- 接入配置示例:src/examples/config.ts
- 底层数据层:grafast/dataplan-pg/README.md、utils/pg-introspection/README.md
- 执行引擎:grafast/grafast/README.md