Promptgres：PostgreSQL元数据工具，提升AI编程效率与数据文档化

1. 项目概述：Promptgres，一个为AI开发时代量身定制的PostgreSQL元数据工具

如果你和我一样，日常开发重度依赖像Cursor这类AI编程助手，那你肯定遇到过这个痛点：当你试图让AI帮你写一个复杂的SQL查询，或者生成一个与数据库交互的API时，你不得不花大量时间在聊天框里粘贴表结构、字段名、枚举值。这个过程不仅繁琐，而且容易出错，上下文一旦切换，AI助手就可能“忘记”你的数据库长什么样。Promptgres这个项目，就是为了解决这个“最后一公里”的问题而生的。它本质上是一个轻量级的Python库和命令行工具，专门用于从PostgreSQL数据库中提取、转换和生成结构化的元数据描述文件。这些文件，无论是XML还是YAML格式，都能成为你与AI助手（如Cursor、GitHub Copilot）高效协作的“上下文燃料”，让AI真正理解你的数据模型，从而生成更准确、更贴合业务逻辑的代码和SQL。

它的核心工作流非常清晰：连接你的数据库，将表、列、约束、枚举等元数据导出为结构化的XML；然后，将这些XML转换成一个可读性极强的YAML模板，你可以在其中为每个表、每个字段添加自然语言描述；最后，它还能反向操作，根据你填写好的YAML描述，生成标准的PostgreSQLCOMMENTSQL语句，直接应用到数据库上，实现文档与代码的同步。这个闭环，完美契合了现代“文档即代码”和“AI辅助开发”的理念。无论你是想提升AI编程效率的数据工程师，还是希望团队拥有统一、可版本化数据字典的后端开发者，Promptgres都提供了一个极其优雅的解决方案。

2. 核心设计思路：为什么是“Prompt” + “gres”？

这个项目的名字起得很妙，直接点明了它的两大使命：为“提示词（Prompt）”工程服务，对象是“PostgreSQL（gres）”。我们来拆解一下其背后的设计哲学。

2.1 解决AI开发中的“上下文饥饿”问题

在AI编程中，上下文窗口是宝贵的资源。你不可能把整个数据库的CREATE TABLE语句都塞进提示词。Promptgres的做法是进行“无损压缩”和“结构化提取”。它不关心你的数据，只关心数据的“蓝图”——也就是元数据。通过导出为XML，它获得了一个机器可读、结构完整的数据库快照。这个快照比纯SQL DDL更规整，比直接查询information_schema更聚焦（因为它经过了筛选和格式化）。

更重要的是第二步：生成YAML模板。YAML对人类极其友好，它的缩进结构和键值对形式，天生适合编写描述性文本。这个模板文件，就是你和AI之间的一份“合约”。你在这里用自然语言说明users表的status字段为什么会有‘pending’，‘active’，‘banned’三个值，每个值在业务上代表什么。当你下次让AI“生成一个封禁用户的函数”时，你只需要附上这个YAML文件，AI就能基于你对status=‘banned’的定义，生成逻辑准确的代码，而不是凭空猜测。

2.2 保持工具链的纯粹性与可组合性

从代码仓库的结构就能看出，这是一个为现代Python开发生态精心打造的项目。它使用uv作为包管理和运行工具，这比传统的pip+venv组合更快速、更一致。使用Ruff进行极速的代码检查和格式化，用pytest进行测试并设定覆盖率门槛。这些选择让项目的贡献门槛很低，任何熟悉当前Python最佳实践的开发者都能立刻上手。

它的库API设计也体现了“单一职责”和“纯函数”的思想。核心的转换逻辑（如XML到YAML的渲染）被设计为不依赖数据库连接的纯函数。这意味着你可以轻松地为这些函数编写单元测试，无需搭建复杂的数据库测试环境。这种设计让Promptgres不仅仅是一个黑盒脚本，更是一个可以被集成到更大自动化流程（比如CI/CD中的数据库文档同步）中的可靠组件。

2.3 实现文档与数据库的双向同步

很多团队都有数据字典，但往往是陈旧的Word文档或零散的Wiki页面，与真实的数据库严重脱节。Promptgres通过descriptions sql子命令，将YAML描述反向编译成COMMENT ON语句，使得维护文档的行为直接变成了执行SQL迁移脚本。你可以把add_comments.sql文件纳入你的数据库迁移工具（如Flyway, Liquibase, Alembic）中，确保每次表结构变更后，对应的描述也能随之更新。这解决了元数据管理中最棘手的“同步”问题。

3. 从零开始：安装与环境配置实操

让我们抛开README，从实战角度走一遍安装和初步使用的流程。这里会包含一些官方文档可能没细说的细节。

3.1 前置条件与工具选型

首先，你需要一个可访问的PostgreSQL数据库（版本10以上均可）。本地用Docker快速拉起一个是最方便的选择：

docker run -d --name promptgres-pg -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:15

接下来是Python环境。我强烈推荐使用uv，它不仅安装包飞快，还能完美处理项目依赖隔离。如果你还没安装，用以下命令（以MacOS/Linux为例）：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装后，新建一个项目目录并进入，然后克隆Promptgres仓库（或者你也可以直接将其作为依赖安装，但为了开发和学习，我们直接克隆）：

mkdir my-promptgres-workspace && cd my-promptgres-workspace git clone https://github.com/sunanmau5/promptgres.git cd promptgres

3.2 依赖安装与虚拟环境

项目使用pyproject.toml管理依赖，并通过uv安装。注意看项目中的uv sync命令，它指定了--group dev --group test。这意味着它会安装运行依赖、开发依赖和测试依赖。

注意：uv在同步时，会根据pyproject.toml中的[project]和[tool.uv.sync]等配置，创建一个独立的虚拟环境。你不需要手动source venv/bin/activate，uv run命令会自动在正确的上下文中执行。这是uv带来的一个非常棒的体验改进。

直接运行安装命令：

uv sync --group dev --group test

这个命令会完成所有依赖的下载和虚拟环境准备。如果一切顺利，你现在就可以使用uv run来执行项目内的任何命令了。

3.3 数据库连接配置的几种姿势

Promptgres CLI支持多种配置方式，优先级从高到低是：命令行参数 > 环境变量 >.env文件。对于日常使用，我推荐使用.env文件，因为它安全（可以不被提交到Git）且方便。

在你的项目根目录（promptgres/下）创建.env文件：

# .env PGHOST=localhost PGPORT=5432 PGDATABASE=postgres # 这里替换成你的实际数据库名 PGUSER=postgres PGPASSWORD=postgres # 生产环境务必使用更安全的方式，如PGPASSFILE

实操心得：千万不要将包含真实密码的.env文件提交到版本库！确保它在你的.gitignore列表中。对于团队协作，可以提交一个.env.example文件，列明需要的变量但不包含敏感值。

如果你想临时连接另一个数据库，可以直接在命令前设置环境变量，这是最灵活的方式：

PGDATABASE=my_app_db uv run promptgres schema export --output my_schema.xml

4. 核心工作流深度解析与实战

现在，我们进入最核心的部分，一步步拆解Promptgres的四个主要子命令，看看它们如何串联起一个完整的工作流。

4.1 第一步：导出元数据（schema export/enums export）

这两个命令是数据采集的起点。它们直接连接到你的数据库，从系统目录中读取信息。

# 导出整个模式（表、视图、列、约束等） uv run promptgres schema export --output schema/pg_schema.xml # 专门导出所有枚举类型及其值 uv run promptgres enums export --output schema/pg_enums.xml

背后原理：这两个命令本质上是在执行一系列精心构造的SQL查询，查询的是pg_catalog和information_schema中的表。例如，为了获取表信息，它可能会查询pg_class（存储关系）和pg_attribute（存储列），并关联pg_namespace（模式）进行过滤。导出的XML结构是自定义的，但设计得非常直观，包含了对象的完整层次关系。

注意事项：

• 权限：执行导出的数据库用户至少需要具有对目标数据库的CONNECT权限，以及对information_schema相关视图或pg_catalog表的SELECT权限。通常，数据库所有者或具有pg_read_all_data角色的用户都可以。
• 输出目录：项目默认将schema/目录放在了.gitignore中，这意味着你生成的pg_schema.xml等文件不会被意外提交。这是一个很贴心的默认设置，因为这类文件可能包含内部业务结构信息。如果你希望版本化这些元数据，需要修改.gitignore。
• 文件内容：打开生成的XML文件看一眼，你会看到类似<table name="users" schema="public">这样的节点，里面详细列出了每一列的名称、类型、是否可为空、默认值等。这就是你数据库的“骨骼”。

4.2 第二步：生成描述模板（descriptions template）

这是将机器可读的元数据转换为人机皆宜的编辑界面的关键一步。

uv run promptgres descriptions template \ --schema schema/pg_schema.xml \ --output schema/column_descriptions.yaml

这个命令会读取上一步生成的XML，然后创建一个YAML文件。这个YAML文件的结构大致如下：

public.users: description: |- # 在这里描述 `users` 表是做什么的。 # 例如：存储系统所有注册用户的核心信息表。 columns: id: description: |- # 主键，自增ID。 email: description: |- # 用户的唯一登录邮箱地址。 status: description: |- # 用户账户状态。枚举值：'pending'（待激活），'active'（活跃），'banned'（已封禁）。

核心价值：这个模板文件为你提供了一个结构化的“填空题”清单。#开头的行是提示，你可以直接在这些提示下方用自然语言填写描述。YAML的|-符号表示保留换行符的块标量，非常适合编写多行描述。

实操技巧：

1. 描述风格：描述应简洁、业务化。避免使用“这个字段是ID”这种同义反复，而是说明“订单的唯一标识符，用于关联支付和物流”。
2. 枚举说明：对于枚举字段，务必解释每个值的业务含义。这是AI生成正确业务逻辑代码的关键。
3. 批量处理：你可以用任何文本编辑器或IDE（如VSCode, PyCharm）打开这个YAML文件，利用多光标编辑等功能快速填写大量类似的描述。

4.3 第三步：生成SQL注释语句（descriptions sql）

当你和团队一起完善了YAML描述文件后，就需要将这些文档“灌注”回数据库。

uv run promptgres descriptions sql \ --descriptions schema/column_descriptions.yaml \ --output schema/add_comments.sql

执行这个命令后，你会得到一个add_comments.sql文件，里面充满了COMMENT ON语句：

COMMENT ON TABLE public.users IS '存储系统所有注册用户的核心信息表。'; COMMENT ON COLUMN public.users.email IS '用户的唯一登录邮箱地址。'; COMMENT ON COLUMN public.users.status IS '用户账户状态。枚举值：''pending''（待激活），''active''（活跃），''banned''（已封禁）。';

关键点：生成的SQL是幂等的吗？这是一个好问题。标准的COMMENT ON语句，如果对象上已有注释，它会覆盖原有的注释。所以，你可以安全地多次运行这个脚本，结果将是最终一致的。你可以使用psql或你喜欢的数据库管理工具来执行这个SQL文件：

psql -h localhost -U postgres -d your_database -f schema/add_comments.sql

4.4 第四步：在AI编程助手（Cursor）中的应用

至此，你已经拥有了一个富含语义信息的数据库描述文件（column_descriptions.yaml）。现在，看看它如何改变你与Cursor的协作方式。

传统低效方式：

你： “帮我写一个查询，找出所有状态是活跃的用户，并显示他们的邮箱。” Cursor： （因为没有上下文，可能生成一个语法正确但表名、列名都是猜的查询）

使用Promptgres后的高效方式：

1. 在Cursor中打开你的代码文件。
2. 将column_descriptions.yaml文件的内容，或者其中与当前任务相关的部分（例如public.users表的整个段落），粘贴到Cursor的聊天上下文（通常是输入框上方的“附加上下文”区域，或直接放在聊天消息中）。
3. 然后提问：

你： “基于上面的数据结构，写一个SQL查询，获取所有status为‘active’的用户的email。” Cursor： （因为它已经“知道”users表有email和status列，并且status的‘active’代表活跃用户）它会生成：

SELECT email FROM public.users WHERE status = 'active';

更高级的用法：你甚至可以让AI基于这些描述生成更复杂的代码。例如，附上描述后提问：“为这个users表生成一个Python Pydantic模型”或“创建一个GraphQL类型定义”。AI生成的代码字段名和类型都会非常准确。

5. Python API浅析与集成可能性

虽然CLI已经足够强大，但Promptgres也提供了精简的Python API，让你可以将其集成到自己的自动化脚本或应用中。

from promptgres import build_schema_collection, render_schema_xml # 假设你从其他地方获取了数据库连接信息，并自己查询了元数据 # `build_schema_collection` 是一个纯函数，它接收类似ORM的元数据对象，构建内部结构 # `render_schema_xml` 将内部结构渲染为XML字符串

从源码可以看出，它的库API设计得非常克制。核心的转换逻辑（如render_descriptions_yaml）都是纯函数，接收特定格式的数据结构，返回渲染后的字符串。这种设计带来了极佳的可测试性。

集成示例：假设你有一个Django项目，你想在每次模型（Model）变更后自动生成并更新数据库注释。你可以写一个自定义的Django管理命令：

# your_app/management/commands/generate_pg_comments.py from django.core.management.base import BaseCommand from django.db import connection import subprocess import os class Command(BaseCommand): help = '使用Promptgres生成并应用数据库注释' def handle(self, *args, **options): # 1. 设置环境变量指向你的Django数据库 os.environ.update({ 'PGHOST': 'localhost', 'PGDATABASE': connection.settings_dict['NAME'], # ... 其他连接信息 }) # 2. 调用Promptgres CLI（通过uv run） subprocess.run(['uv', 'run', 'promptgres', 'schema', 'export', ...], check=True) subprocess.run(['uv', 'run', 'promptgres', 'descriptions', 'template', ...], check=True) # ... (这里需要有一个机制来更新YAML描述，可能是读取Django模型的verbose_name) subprocess.run(['uv', 'run', 'promptgres', 'descriptions', 'sql', ...], check=True) # 3. 执行生成的SQL with connection.cursor() as cursor: with open('schema/add_comments.sql') as f: cursor.execute(f.read()) self.stdout.write(self.style.SUCCESS('成功更新数据库注释'))

这个例子展示了如何将Promptgres嵌入到现有工作流中，实现数据库文档的自动化同步。

6. 开发、测试与发布：参与贡献指南

Promptgres项目本身采用了一套非常现代和规范的开发流程，如果你想为其贡献代码或只是想学习一下优秀的开源项目配置，这部分很有价值。

6.1 代码质量保障：Ruff与Pytest

项目使用Ruff同时进行代码风格检查（Lint）和格式化（Format）。这比单独配置flake8、isort、black要简单高效得多。

# 检查代码风格和潜在错误 uv run ruff check . # 自动修复所有可自动修复的问题 uv run ruff check --fix . # 检查代码格式是否符合要求 uv run ruff format --check . # 自动格式化代码 uv run ruff format .

测试使用pytest，并且设定了覆盖率要求（通常在pyproject.toml或setup.cfg中配置）。运行测试并查看覆盖率报告：

uv run pytest # 通常配合覆盖率插件，生成报告 uv run pytest --cov=promptgres tests/

避坑技巧：在提交代码前，务必确保ruff check .和ruff format --check .通过。这能保证你的代码风格与项目主体一致，提高代码审查通过的概率。许多项目会将这两条命令配置为CI/CD流水线的必过项。

6.2 提交规范：Conventional Commits

项目采用了Angular风格的约定式提交。这意味着你的每次提交信息都需要遵循特定格式：

<type>(<scope>): <subject> <body> <footer>

常用的type包括：

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• refactor: 重构（既不新增功能，也不修复bug）
• test: 增加或修改测试
• chore: 构建过程或辅助工具的变动

项目提供了工具来帮助检查和生成版本号：

# 安装发布相关工具 uv sync --group release # 检查最近几次提交的格式 uv run cz check --rev-range HEAD~5..HEAD # 根据提交历史，建议下一个版本号（如 patch, minor, major） uv run python scripts/release.py suggest

使用这种提交规范，最大的好处是可以自动化生成CHANGELOG.md，并且让版本号的升级（语义化版本）有据可依。

6.3 发布流程：手动但辅助完善的流水线

项目的发布流程不是全自动的，而是“辅助式手动”。这平衡了灵活性和可靠性。发布前，你需要确保所有检查通过：

uv sync --group dev --group test --group release uv run ruff check . uv run ruff format --check . uv run pytest uv build # 构建分发包

然后，使用发布助手脚本准备发布：

uv run python scripts/release.py draft --version 0.2.0

这个命令会干运行，展示它将如何更新CHANGELOG.md和pyproject.toml。确认无误后，使用--apply参数实际执行：

uv run python scripts/release.py prepare --version 0.2.0 --apply

之后，按照脚本输出的提示，完成提交、打标签和推送：

git commit -m "chore(release): 0.2.0" git tag -a v0.2.0 -m "v0.2.0" git push origin main git push origin v0.2.0

最后，你需要手动到GitHub仓库页面，基于新推送的v0.2.0标签创建一个Release，并将uv build生成的发行包（在dist/目录下）上传。

7. 常见问题与排查技巧实录

在实际使用和集成Promptgres的过程中，你可能会遇到一些典型问题。这里记录了我遇到过的坑和解决方法。

7.1 连接数据库失败

问题现象：执行schema export时，报错如psycopg2.OperationalError: connection to server at "localhost" (::1) failed。

排查步骤：

1. 检查基础连接：首先用psql命令行或图形化工具（如pgAdmin）尝试连接，确认数据库服务是否运行、主机端口是否正确、防火墙是否开放。
2. 检查环境变量：运行env | grep PG，确认当前shell环境中的PG*变量是否设置正确。记住，.env文件需要被加载（如果你用的是uv run，它通常会自动加载项目根目录的.env）。
3. 验证密码：如果使用密码认证，确保密码正确。可以尝试在命令行中直接指定：PGPASSWORD=yourpass uv run promptgres ...。
4. 检查认证方法：对于本地PostgreSQL，有时pg_hba.conf文件配置为peer或ident认证，这要求操作系统用户与数据库用户同名。可以尝试修改为md5或scram-sha-256密码认证。

7.2 生成的YAML模板文件为空或缺少对象

问题现象：column_descriptions.yaml文件里只有寥寥几个表，或者内容很少。

可能原因与解决：

1. 权限不足：连接的用户可能没有访问某些模式（如非public模式）或系统表的权限。确保连接用户有足够权限。可以尝试用超级用户（如postgres）连接测试。
2. 模式过滤：Promptgres可能默认只导出了特定模式（如public）。查看promptgres schema export --help，看是否有--schema或--exclude-schema参数来控制导出的模式范围。目前版本的CLI可能默认导出所有用户模式，但需要确认。
3. 数据库为空：确认你连接的数据库里确实有创建好的表和枚举。

7.3 执行生成的SQL注释语句时报错

问题现象：运行add_comments.sql时，提示“关系 "xxx" 不存在”或“重复的注释”。

排查与解决：

1. 对象不存在：确保你运行SQL的数据库和生成元数据的数据库是同一个，并且中间没有发生表结构变更。最好在同一个事务或短时间内完成“导出-编辑-应用”的循环。
2. 对象名包含特殊字符或大小写：如果表名或列名包含大写字母或特殊字符，在SQL中需要用双引号括起来。检查生成的SQL语句是否正确使用了引号。Promptgres应该会处理好这些细节。
3. 注释已存在：COMMENT ON是覆盖操作，通常不会因注释已存在而报错。如果报“重复”，可能是其他约束问题。可以尝试先执行COMMENT ON TABLE x IS NULL;来清空注释，再执行新的注释语句。

7.4 如何与团队共享和维护YAML描述文件？

挑战：column_descriptions.yaml文件需要团队共同维护，但schema/目录默认被.gitignore了。

解决方案：

1. 移除忽略：如果你们团队认为数据库模式描述是应该版本化的资产，可以修改项目根目录的.gitignore文件，移除或注释掉schema/行。但务必确保XML文件（包含原始元数据）不包含敏感信息。
2. 分离文件：一个更清晰的策略是：
   • 继续将schema/pg_schema.xml和schema/pg_enums.xml保留在.gitignore中，因为它们是从生产或开发数据库动态生成的，可能变化频繁且包含内部信息。
   • 将schema/column_descriptions.yaml移到一个新的目录，比如docs/data_dictionary/，并将其纳入版本控制。这样，YAML文件就成为了团队共同维护的、与代码同步的“数据字典”文档。
   • 修改命令的输出路径：uv run promptgres descriptions template --schema schema/pg_schema.xml --output docs/data_dictionary/descriptions.yaml

7.5 在CI/CD中集成自动生成注释

场景：希望在每次应用部署、数据库迁移后，自动更新数据库注释。

思路：在CI/CD流水线（如GitHub Actions, GitLab CI）中增加一个步骤。

1. 在流水线中安装uv和项目依赖。
2. 使用具有数据库访问权限的秘钥配置好PG*环境变量。
3. 执行导出、生成SQL的步骤。
4. 使用一个数据库客户端（如psql）或编程语言驱动（如psycopg2）来执行生成的add_comments.sql。

关键点：确保流水线中的数据库连接是安全的，并且执行顺序正确（在数据库迁移之后，应用启动之前执行注释更新）。同时，要考虑如何处理YAML描述的更新——是手动维护一个版本化的YAML文件，还是在流水线中基于某个“描述源”动态生成？前者更可控，后者更自动化，需要根据团队流程权衡。

我个人在实际使用Promptgres几个月后，最大的体会是它极大地减少了我与AI助手之间的“沟通摩擦”。以前需要反复粘贴、解释，现在只需要在开始一个新功能模块时，运行一遍这个工具链，把生成的YAML描述文件放在手边。当AI生成的代码第一次就准确引用了正确的字段和枚举值时，那种顺畅感是实实在在的效率提升。它不是一个庞大的框架，而是一个锋利、专注的小工具，完美地嵌入了现代数据驱动开发的工具链缝隙中。如果你也在用PostgreSQL和AI编程，花半小时试试它，很可能就回不去了。