AI Agent 总把数据库猜错？LLMSchema 把 PostgreSQL、MySQL 和 SQLite 变成可读上下文
AI 编码 Agent 修改后端代码时，最容易出错的地方往往不是语法，而是数据库上下文：它需要从迁移文件、ORM 模型和业务代码里“猜”出表结构，结果可能遗漏索引、误解外键，甚至把已经删除的字段当成现状。LLMSchema 是一个 MIT 许可的 Go 工具，专门把 PostgreSQL、MySQL 和 SQLite 的数据库结构提取成紧凑 Markdown，供 Agent 直接阅读。
为什么单独生成一份 schema 文档
LLMSchema 的思路不是让 Agent 再读一套复杂的数据库工具输出，而是生成一份适合上下文窗口的文档。它会记录表、列、类型、索引、约束和关系，默认输出到一个 Markdown 文件；也可以为每张表生成独立文件，让 Agent 只读取当前任务相关的部分。
这解决了两个实际问题：第一，数据库才是运行时事实，迁移历史只是演变过程；第二，完整数据库可能很大，把全部表结构塞进每次对话会浪费上下文。项目 README 也明确提醒，它面向开发数据库和 AI 辅助编码，不应替代生产环境的关键文档。
安装和第一次运行
项目提供 Go 安装方式，也提供 macOS/Linux 的安装脚本。安装 CLI 后，可以通过环境变量传入连接串：
export DATABASE_URL="postgres://user:***@localhost:5432/mydb" llmschema -o schema.md
也可以显式传递 --db-url：
llmschema --db-url "postgres://user:***@localhost:5432/mydb" -o schema.md
目前支持的连接串形式包括 postgres://、mysql:// 和 sqlite://。如果同时设置了 DATABASE_URL 和 --db-url，显式参数优先。连接信息建议通过环境变量或密钥管理器注入，不要把真实密码写入脚本、提交记录或 Agent 可见的公共文档。
按任务缩小上下文
默认情况下，工具会生成完整 schema；对于大型项目，更实用的是筛选表：
# 只生成用户和订单相关表 llmschema -o schema-core.md -t "users,orders,comments" # 排除迁移和审计表 llmschema -o schema.md -e "migrations,audit_logs"
如果希望 Agent 按需读取表文件，可以使用目录输出：
llmschema -d docs/db-schema
目录中会有概览文件、每张表的 Markdown 文件，以及用于跟踪生成文件的 manifest。团队可以在 AGENTS.md 或 CLAUDE.md 中加入一条简单约定：数据库 schema 文档位于 docs/db-schema/。这样 Agent 先看概览，再根据任务打开相关表，不必把整个数据库复制进提示词。
让文档跟着迁移更新
一次性生成文档还不够，关键是让它成为迁移流程的一部分。README 给出了 Makefile 集成思路：迁移完成后重新运行 LLMSchema。
.PHONY: migrate schema migrate: # 示例：替换成项目实际使用的迁移命令 goose postgres "$(DATABASE_URL)" up $(MAKE) schema schema: go run github.com/tordrt/llmschema/cmd/llmschema@latest -o schema.md
在团队里使用时，建议把生成的文档视为构建产物：本地开发和 CI 都可以检查它是否发生变化；如果项目不希望把结构提交到仓库，也可以在隔离环境中生成后提供给 Agent。无论采用哪种方式，都应避免把生产数据库凭据和不应公开的表数据暴露给第三方模型。
它能改善什么，不能保证什么
这类 schema 文档特别适合让 Agent 正确理解字段类型、主键、唯一约束、复合索引和表间关系。面对“给订单查询增加一个过滤条件”或“为用户表添加 API 字段”这类任务，Agent 可以先确认真实字段和约束，再修改代码，减少凭空假设。
但 LLMSchema 不会自动理解业务语义，也不会判断某个索引是否适合线上负载。数据库结构可能是正确的，业务规则仍然可能隐藏在服务代码、权限策略或触发器里。因此更稳妥的流程是：生成 schema，写入 Agent 的项目说明；让 Agent 提出修改计划；在开发数据库执行并测试；最后由开发者检查 SQL、迁移回滚策略和权限影响。
LLMSchema 的价值在于把“从代码猜数据库”变成“读取一份由数据库生成的事实摘要”。它是一个很小的 Go CLI，却刚好补上了 AI 编码工作流中经常被忽略的上下文层：让 Agent 先看清数据模型，再开始写代码。