pg-introspection 实践指南:基于 PostgreSQL 系统目录的强类型内省库

原创2026-09-23 23:08:201,889 阅读
文章标签:后端API网关

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 一节):

  1. 把 makeIntrospectionQuery() 生成的 SQL 发给数据库;
  2. 取第一行的 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。

这些接口有三个值得注意的设计:

  1. OID 统一为字符串类型 PgOid(introspection.ts),因为 JSON 无法保留 PostgreSQL 的 oid 整数精度,统一字符串可避免精度丢失。
  2. 枚举型字段的取值以文档注释说明。例如 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 官方目录文档。
  3. 版本感知的可选字段。部分字段标注了 @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 中明确了两点:

  1. 直接沿用 PostgreSQL 列名是有意为之(by design),即使不熟悉系统目录的开发者会觉得某些名字晦涩(如 relnatts、coninhcount)。好处是文档与 PostgreSQL 官方目录一一对应、无需记忆别名映射。
  2. 用 _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):

小结

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。

登录后查看全文
crystal