pg-introspection 实践指南:基于 PostgreSQL 系统目录的强类型内省库
pg-introspection 实践指南:基于 PostgreSQL 系统目录的强类型内省库
pg-introspection 是 Graphile Crystal Monorepo(utils/pg-introspection)中一个强类型的 PostgreSQL 内省(introspection)库:它用一条 SQL 查询把数据库的系统目录(system catalog)快照成结构化 JSON,再由 TypeScript 侧解析为带完整类型定义与文档注释的对象,供 PostGraphile v5、Grafast 等上层工具直接消费。读完本文,你将掌握 makeIntrospectionQuery() + parseIntrospectionResults() 的完整用法、内省结果中 19 种实体类型与"访问器"(accessor)的关系,以及其命名约定与扩展资源过滤等设计细节。
pg-introspection 是什么
pg-introspection 的定位是"面向 PostgreSQL 的强类型内省库"。它的独特之处在于:类型定义并非手写,而是根据 PostgreSQL 系统目录文档自动生成的——每个属性/类型的 TypeScript 文档注释同样取自 PostgreSQL 官方文档,因此在编辑器中悬停即可看到该列(如 pg_class.relkind、pg_attribute.attnotnull)的权威说明。
从仓库结构看,它位于 Monorepo 的 utils/pg-introspection 目录下,其 package.json 声明版本 1.0.1、Node.js >= 22、仅依赖 tslib,是 PostGraphile v5 构建 GraphQL schema 时读取数据库结构的底层基础设施之一。它同时导出:
makeIntrospectionQuery/parseIntrospectionResults(核心 API)reservedWords(PostgreSQL 保留字列表)parseSmartComment(解析 smart comment 标签)- ACL 解析工具
aclContainsRole、entityPermissions、expandRoles、resolvePermissions与AclObject类型
快速上手:两步拿到强类型内省结果
官方用法高度精简,核心只有两个步骤(见 utils/website/pg-introspection/index.md 的 Usage 一节):
- 把
makeIntrospectionQuery()生成的 SQL 发给数据库; - 取第一行的
introspection字段(JSON 文本),交给parseIntrospectionResults()解析,得到强类型的内省对象。
以下是与 pg 模块配合的完整可运行示例(继承自原文档,保持原样可复制):
import {
makeIntrospectionQuery,
parseIntrospectionResults,
} from "pg-introspection";
import { Pool } from "pg";
const pool = new Pool({
connectionString: "postgres://localhost:5432/my_database",
});
async function main() {
const sql = makeIntrospectionQuery();
const { rows } = await pool.query(sql);
const introspection = parseIntrospectionResults(rows[0].introspection);
console.log(
`The ${introspection.database.datname} DBA is ${
introspection.database.getDba()?.rolname ?? "-"
}`,
);
}
main();
示例中 introspection.database.datname 是数据库名,introspection.database.getDba() 是访问器——它跨目录(pg_database.datdba → pg_roles)解析出所有者角色对象。即便没有建表、没有任何用户表,这条查询也能返回数据库级元数据,适合作为接入内省能力的第一段代码。
深入 makeIntrospectionQuery:一条 SQL 打包 18 个系统目录
makeIntrospectionQuery() 的实现位于 utils/pg-introspection/src/introspection.ts。从源码可见它是一条大型 CTE 查询,一次性从 18 个系统目录/视图取数:
| CTE 名称 | 数据来源 | 说明 |
|---|---|---|
database |
pg_database |
仅当前数据库(datname = current_database()) |
namespaces |
pg_namespace |
排除 information_schema |
classes |
pg_class |
表/索引/视图/物化视图/序列等,附 pg_relation_is_updatable 计算的 updatable_mask |
attributes |
pg_attribute |
仅 attnum > 0(排除系统列) |
constraints |
pg_constraint |
约束 |
procs |
pg_proc |
排除返回伪类型 2279(trigger 函数)的例程 |
roles |
pg_roles |
所有角色(含密码脱敏视图) |
auth_members |
pg_auth_members |
角色成员关系 |
types |
pg_type |
用户 schema 类型 + pg_catalog 类型 |
enums |
pg_enum |
枚举值 |
extensions |
pg_extension |
已安装扩展 |
indexes |
pg_index |
索引 |
inherits |
pg_inherits |
继承/分区层级 |
languages |
pg_language |
过程语言 |
policies |
pg_policy |
行级安全策略 |
ranges |
pg_range |
范围类型 |
depends |
pg_depend |
仅 deptype IN ('a','e') 的依赖关系 |
descriptions |
pg_description |
COMMENT 注释 |
am |
pg_am |
访问方法(如 heap、btree) |
注意其中两类过滤策略:
namespaces/classes/constraints/procs等以nspname not like 'pg\_%'排除系统 schema(pg_catalog、pg_toast等),避免内省结果被内置对象淹没;types例外地包含pg_catalog(typnamespace = 'pg_catalog'::regnamespace),因为用户列的类型(如int4、text)几乎都指向系统类型,缺了它们类型链路会断裂。
查询最终通过 json_build_object 输出一个 JSON 对象(见 introspection.ts),除上述数组外还包含四个元信息字段:
catalog_by_oid:pg_class中 OID → 目录名(如"1259": "pg_class")的映射,用于把classid这类 OID 反查回目录名;current_user:执行内省的用户名;pg_version:完整版本串(如PostgreSQL 13.4 (Ubuntu ...));introspection_version:当前为1——源码注释说明"未来可能更换内省查询,一旦发生不兼容变更就提升此版本号",调用方可据此判断结果格式。
parseIntrospectionResults:解析、索引与增强
parseIntrospectionResults(introspectionResults, includeExtensionResources = false) 的定义在 utils/pg-introspection/src/index.ts,它只是 augmentIntrospection 的薄封装。真正的工作在 utils/pg-introspection/src/augmentIntrospection.ts 中完成,大致三步:
1. 解析 JSON。 JSON.parse 得到 Introspection 原始对象(augmentIntrospection.ts)。
2. 构建 O(1) 查找索引。 createLookups() 把 17 个数组转成 26 个 Map/Record(如 classById、typeById、namespaceByName、attributesByRelId、constraintsByRelid、descriptionByDescriptionKey 等),并为属性/约束/枚举按 attnum、conname、enumsortorder 排序。源码注释(augmentIntrospection.ts)明确这些索引"用于把 O(N) 查找变成 O(1)"。这正是后续所有访问器能快速跨目录跳转的基础。
3. 默认剔除扩展资源。 includeExtensionResources 默认为 false:通过 depends 中 deptype = 'e'(扩展成员)的依赖记录,把属于扩展的函数、类、属性、约束、类型从结果中批量删除(augmentIntrospection.ts)。这意味着默认内省结果只包含"用户自己的"数据库对象;若你需要分析扩展贡献的对象(如 postgis 提供的函数/表),应传入 true。
Accessors:惰性求值 + 缓存的跨目录导航
内省结果的每个实体上都被"混入"了一组 访问器(accessor)函数,用于把 OID 外键展开成真实对象、跟随关系。官方说明见 utils/website/pg-introspection/accessors.md,其关键特性是惰性求值与结果缓存:
这些函数通常是惰性求值的——第一次调用时可能需要昂贵的查找(例如从记录列表中找出相关记录),但结果会被缓存,下一次调用近乎瞬时。
缓存由 memo() 工具函数实现(augmentIntrospection.ts):首次调用执行并保存结果,之后直接返回缓存值;而 _caches.expandRoles 则为需要复合计算的结果预留了缓存空间。
典型用法(继承自原文档):
const myTable = introspection.classes.find((rel) => rel.relname === "my_table");
const myTableAttributes = myTable.getAttributes();
const myColumn = myTable.getAttribute({ name: "my_column" });
const myColumnDescription = myColumn.getDescription();
访问器的完整清单可以在 utils/pg-introspection/src/index.ts 的模块增强声明中找到,也可以直接在编辑器中用 TypeScript 自动补全浏览。按实体分类的核心访问器如下:
Introspection:getCurrentUser()、getNamespace({id|name})、getClass({id})、getConstraint({id})、getProc({id})、getRoles({id})、getType({id})、getEnum({id})、getExtension({id})、getIndex({id})、getLanguage({id})PgDatabase:getDba()(源码标注@deprecated,建议改用getOwner())、getOwner()、getACL()PgClass(表/视图等):getNamespace()、getType()、getOfType()、getOwner()、getAttributes()、getAttribute({name|number})、getConstraints()、getForeignConstraints()、getIndexes()、getInherited()、getAccessMethod()、getDescription()、getTags()、getACL()PgAttribute(列):getClass()、getType()、getDescription()、getTags()、getACL()PgConstraint(约束):getNamespace()、getClass()、getAttributes()、getForeignClass()、getForeignAttributes()(外键被引用表及其列)、getType()PgProc(函数):getNamespace()、getOwner()、getReturnType()、getArguments()——后者返回带isIn/isOut/isVariadic/hasDefault/type/name的PgProcArgument[],并正确处理proallargtypes与proargtypes两种形态PgType(类型):getNamespace()、getClass()(复合类型的表)、getElemType()(数组元素类型)、getArrayType()、getEnumValues()、getRange()PgIndex:getIndexClass()、getClass()、getKeys()(返回Array<PgAttribute | null>,null表示表达式索引列)PgEnum/PgRange/PgInherits:如getType()、getSubType()、getParent()、getChild()
此外几乎所有实体都带有 getDescription()(对应 COMMENT)、getTags()(smart comment 标签)与 getTagsAndDescription()。例如 PgAttribute.getDescription() 在 augmentIntrospection.ts 中通过 classoid=pg_class + attrelid + attnum 从 pg_description 中定位到列注释。
强类型与版本感知的类型系统
内省结果的类型骨架是 Introspection 接口(utils/pg-introspection/src/introspection.ts),包含 17 个数组字段(namespaces、classes、attributes、constraints、procs、roles、auth_members、types、enums、extensions、indexes、inherits、languages、policies、ranges、depends、descriptions)与 am、database。每个数组元素对应一个 Pg* 接口:
PgDatabase、PgNamespace、PgClass、PgAttribute、PgConstraint、PgProc、PgRoles、PgAuthMembers、PgType、PgEnum、PgExtension、PgIndex、PgInherits、PgLanguage、PgPolicy、PgRange、PgDepend、PgDescription、PgAm。
这些接口有三个值得注意的设计:
- OID 统一为字符串类型
PgOid(introspection.ts),因为 JSON 无法保留 PostgreSQL 的oid整数精度,统一字符串可避免精度丢失。 - 枚举型字段的取值以文档注释说明。例如
PgClass.relkind的注释逐条列出r/i/S/t/v/m/c/f/p/I的含义(introspection.ts),PgConstraint.contype列出c/f/n/p/u/t/x(introspection.ts),PgProc.provolatile说明i/s/v三种稳定性语义。这些注释直接来自 PostgreSQL 官方目录文档。 - 版本感知的可选字段。部分字段标注了
@remarks Only in xx.x,例如PgClass.relallfrozen仅 18.x、PgClass.relhasoids仅 11.x/10.x、PgAttribute.attgenerated仅 12.x–18.x、PgConstraint.conenforced仅 18.x。这类字段被声明为?可选属性,保证同一份类型定义能安全适配不同 PostgreSQL 大版本——这也是"自动从官方文档生成"带来的直接收益。
命名约定:用系统目录原生列名,_id 而非 oid
关于字段命名,官方在 utils/website/pg-introspection/naming.md 中明确了两点:
- 直接沿用 PostgreSQL 列名是有意为之(by design),即使不熟悉系统目录的开发者会觉得某些名字晦涩(如
relnatts、coninhcount)。好处是文档与 PostgreSQL 官方目录一一对应、无需记忆别名映射。 - 用
_id而不是oid:因为较老版本的 PostgreSQL 在select *时不会显式列出oid列,于是库在 SQL 中显式把pg_class.oid、pg_namespace.oid等别名成_id加入选择集(见 introspection.ts 等 CTE 中的select pg_database.oid as _id, *模式),统一作为行标识符。
进阶能力:ACL 解析与 smart comment
除基础内省外,库还提供两套实用工具:
ACL 权限解析。 utils/pg-introspection/src/acl.ts 提供 parseAcls(内部)、aclContainsRole、entityPermissions、expandRoles、resolvePermissions 等函数,把 pg_class.relacl、pg_attribute.attacl、pg_database.datacl 等 aclitem 数组解析为结构化 AclObject<a href="https://link.gitcode.com/i/ced554a01cd20c9d5a8a87a1192038bd" target="_blank">]。数据库、schema、表、列、函数各自携带 ACL(getACL() 按对象类型选择 OBJECT_DATABASE/OBJECT_SCHEMA/OBJECT_TABLE/OBJECT_SEQUENCE/OBJECT_COLUMN/OBJECT_FUNCTION,见 [augmentIntrospection.ts)。角色成员关系(含 PUBLIC 角色)通过 auth_members 展开,expandRoles 结果缓存在 _caches.expandRoles 中。
Smart comment 标签。 utils/pg-introspection/src/smartComments.ts 的 parseSmartComment 负责解析 Graphile 生态的 smart comment 语法(如 @name, @omit, @sortable 等),getTags() 即返回解析后的标签字典(PgSmartTagsDict),getTagsAndDescription() 返回 { tags, description } 组合。PostGraphile v5 正是通过这些标签实现无侵入的 schema 定制。
测试与数据校验
仓库为内省结果提供了一组基于真实快照的测试(utils/pg-introspection/tests):
- acl-optimized-test.ts 与 acl-test.ts:验证 ACL 解析在优化前后的一致性;
- rawIntrospectionResults.mts:保存从真实数据库捕获的原始内省 JSON 快照,作为解析逻辑的固定输入;
- scripts/update-raw-introspection-results.mts:
update-raw-introspection-results脚本(见 package.json 的 scripts 字段)负责刷新这些快照——当目标 PostgreSQL 版本或查询发生变化时,可运行yarn update-raw-introspection-results重新捕获。
小结
pg-introspection 把"查询系统目录"这件琐碎工作收敛为一个可复用的强类型管道:makeIntrospectionQuery() 负责在数据库侧一次性取全 18 类目录数据,parseIntrospectionResults() 在客户端完成 JSON 解析、O(1) 索引构建、扩展资源过滤与访问器注入。其自动生成的类型定义、版本感知的可选字段、惰性缓存的访问器体系,以及 ACL / smart comment 等配套能力,使它成为构建数据库驱动工具(如 PostGraphile)时的坚实底座。更多设计说明可继续阅读 utils/website/pg-introspection/index.md、utils/website/pg-introspection/accessors.md 与 utils/website/pg-introspection/naming.md。