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”工程服务对象是“PostgreSQLgres”。我们来拆解一下其背后的设计哲学。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作为包管理和运行工具这比传统的pipvenv组合更快速、更一致。使用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_PASSWORDpostgres -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 promptgres3.2 依赖安装与虚拟环境项目使用pyproject.toml管理依赖并通过uv安装。注意看项目中的uv sync命令它指定了--group dev --group test。这意味着它会安装运行依赖、开发依赖和测试依赖。注意uv在同步时会根据pyproject.toml中的[project]和[tool.uv.sync]等配置创建一个独立的虚拟环境。你不需要手动source venv/bin/activateuv run命令会自动在正确的上下文中执行。这是uv带来的一个非常棒的体验改进。直接运行安装命令uv sync --group dev --group test这个命令会完成所有依赖的下载和虚拟环境准备。如果一切顺利你现在就可以使用uv run来执行项目内的任何命令了。3.3 数据库连接配置的几种姿势Promptgres CLI支持多种配置方式优先级从高到低是命令行参数 环境变量 .env文件。对于日常使用我推荐使用.env文件因为它安全可以不被提交到Git且方便。在你的项目根目录promptgres/下创建.env文件# .env PGHOSTlocalhost PGPORT5432 PGDATABASEpostgres # 这里替换成你的实际数据库名 PGUSERpostgres PGPASSWORDpostgres # 生产环境务必使用更安全的方式如PGPASSFILE实操心得千万不要将包含真实密码的.env文件提交到版本库确保它在你的.gitignore列表中。对于团队协作可以提交一个.env.example文件列明需要的变量但不包含敏感值。如果你想临时连接另一个数据库可以直接在命令前设置环境变量这是最灵活的方式PGDATABASEmy_app_db uv run promptgres schema export --output my_schema.xml4. 核心工作流深度解析与实战现在我们进入最核心的部分一步步拆解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 nameusers schemapublic这样的节点里面详细列出了每一列的名称、类型、是否可为空、默认值等。这就是你数据库的“骨骼”。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的|-符号表示保留换行符的块标量非常适合编写多行描述。实操技巧描述风格描述应简洁、业务化。避免使用“这个字段是ID”这种同义反复而是说明“订单的唯一标识符用于关联支付和物流”。枚举说明对于枚举字段务必解释每个值的业务含义。这是AI生成正确业务逻辑代码的关键。批量处理你可以用任何文本编辑器或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.sql4.4 第四步在AI编程助手Cursor中的应用至此你已经拥有了一个富含语义信息的数据库描述文件column_descriptions.yaml。现在看看它如何改变你与Cursor的协作方式。传统低效方式你 “帮我写一个查询找出所有状态是活跃的用户并显示他们的邮箱。” Cursor 因为没有上下文可能生成一个语法正确但表名、列名都是猜的查询使用Promptgres后的高效方式在Cursor中打开你的代码文件。将column_descriptions.yaml文件的内容或者其中与当前任务相关的部分例如public.users表的整个段落粘贴到Cursor的聊天上下文通常是输入框上方的“附加上下文”区域或直接放在聊天消息中。然后提问你 “基于上面的数据结构写一个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, ...], checkTrue) subprocess.run([uv, run, promptgres, descriptions, template, ...], checkTrue) # ... (这里需要有一个机制来更新YAML描述可能是读取Django模型的verbose_name) subprocess.run([uv, run, promptgres, descriptions, sql, ...], checkTrue) # 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 --covpromptgres tests/避坑技巧在提交代码前务必确保ruff check .和ruff format --check .通过。这能保证你的代码风格与项目主体一致提高代码审查通过的概率。许多项目会将这两条命令配置为CI/CD流水线的必过项。6.2 提交规范Conventional Commits项目采用了Angular风格的约定式提交。这意味着你的每次提交信息都需要遵循特定格式type(scope): subject body footer常用的type包括feat: 新功能fix: 修复bugdocs: 文档更新refactor: 重构既不新增功能也不修复bugtest: 增加或修改测试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。排查步骤检查基础连接首先用psql命令行或图形化工具如pgAdmin尝试连接确认数据库服务是否运行、主机端口是否正确、防火墙是否开放。检查环境变量运行env | grep PG确认当前shell环境中的PG*变量是否设置正确。记住.env文件需要被加载如果你用的是uv run它通常会自动加载项目根目录的.env。验证密码如果使用密码认证确保密码正确。可以尝试在命令行中直接指定PGPASSWORDyourpass uv run promptgres ...。检查认证方法对于本地PostgreSQL有时pg_hba.conf文件配置为peer或ident认证这要求操作系统用户与数据库用户同名。可以尝试修改为md5或scram-sha-256密码认证。7.2 生成的YAML模板文件为空或缺少对象问题现象column_descriptions.yaml文件里只有寥寥几个表或者内容很少。可能原因与解决权限不足连接的用户可能没有访问某些模式如非public模式或系统表的权限。确保连接用户有足够权限。可以尝试用超级用户如postgres连接测试。模式过滤Promptgres可能默认只导出了特定模式如public。查看promptgres schema export --help看是否有--schema或--exclude-schema参数来控制导出的模式范围。目前版本的CLI可能默认导出所有用户模式但需要确认。数据库为空确认你连接的数据库里确实有创建好的表和枚举。7.3 执行生成的SQL注释语句时报错问题现象运行add_comments.sql时提示“关系 xxx 不存在”或“重复的注释”。排查与解决对象不存在确保你运行SQL的数据库和生成元数据的数据库是同一个并且中间没有发生表结构变更。最好在同一个事务或短时间内完成“导出-编辑-应用”的循环。对象名包含特殊字符或大小写如果表名或列名包含大写字母或特殊字符在SQL中需要用双引号括起来。检查生成的SQL语句是否正确使用了引号。Promptgres应该会处理好这些细节。注释已存在COMMENT ON是覆盖操作通常不会因注释已存在而报错。如果报“重复”可能是其他约束问题。可以尝试先执行COMMENT ON TABLE x IS NULL;来清空注释再执行新的注释语句。7.4 如何与团队共享和维护YAML描述文件挑战column_descriptions.yaml文件需要团队共同维护但schema/目录默认被.gitignore了。解决方案移除忽略如果你们团队认为数据库模式描述是应该版本化的资产可以修改项目根目录的.gitignore文件移除或注释掉schema/行。但务必确保XML文件包含原始元数据不包含敏感信息。分离文件一个更清晰的策略是继续将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.yaml7.5 在CI/CD中集成自动生成注释场景希望在每次应用部署、数据库迁移后自动更新数据库注释。思路在CI/CD流水线如GitHub Actions, GitLab CI中增加一个步骤。在流水线中安装uv和项目依赖。使用具有数据库访问权限的秘钥配置好PG*环境变量。执行导出、生成SQL的步骤。使用一个数据库客户端如psql或编程语言驱动如psycopg2来执行生成的add_comments.sql。关键点确保流水线中的数据库连接是安全的并且执行顺序正确在数据库迁移之后应用启动之前执行注释更新。同时要考虑如何处理YAML描述的更新——是手动维护一个版本化的YAML文件还是在流水线中基于某个“描述源”动态生成前者更可控后者更自动化需要根据团队流程权衡。我个人在实际使用Promptgres几个月后最大的体会是它极大地减少了我与AI助手之间的“沟通摩擦”。以前需要反复粘贴、解释现在只需要在开始一个新功能模块时运行一遍这个工具链把生成的YAML描述文件放在手边。当AI生成的代码第一次就准确引用了正确的字段和枚举值时那种顺畅感是实实在在的效率提升。它不是一个庞大的框架而是一个锋利、专注的小工具完美地嵌入了现代数据驱动开发的工具链缝隙中。如果你也在用PostgreSQL和AI编程花半小时试试它很可能就回不去了。