AOCI-CODE Database Cognition 完全指南:把 PostgreSQL、MySQL、openGauss 表结构纳入同一索引
AOCI-CODE Database Cognition 完全指南:把 PostgreSQL、MySQL、openGauss 表结构纳入同一索引
AOCI-CODE 是一个本地优先的 Go 语言 MCP 服务器 + CLI 工具,它的 Database Cognition(数据库认知索引)功能能把 PostgreSQL、MySQL、openGauss 的表结构以"只读证据"方式采集下来,与代码索引一起纳入同一份 Git 版本化的 aoci.database.txt,让 Claude Code、Codex、Cursor、opencode 等编程 Agent 在动手改代码之前,先"读懂"数据库的表、约束和关键规则。
什么是 Database Cognition?为什么需要它 🧭
写代码的 AI Agent 最大的短板之一是:对数据库一无所知。表名叫什么、哪张表是权威数据源、外键关系如何、哪些字段绝不能删——这些信息 Agent 只能靠反复翻迁移脚本和 SQL 文件去猜。
Database Cognition 的做法是给每张表写一行"认知条目"(FRAS 格式),和代码索引共用同一套治理流程:
| 字段 | 回答的问题 | 示例内容 |
|---|---|---|
| F — Function | 这张表的核心职责? | 存储权威的商业订单聚合 |
| R — Relations | 修改时必须一起考虑的表? | customers、payments、audit_events |
| A — API | 外部可依赖的接口/契约? | order_number、OrderRepository、POST_/orders |
| S — 约束 | 代码里推断不出、但改错会出事的规则? | 订单状态流转与台账必须同一事务提交 |
项目自带的真实样例可以直接看到效果:
orders[DB9L]: F:store the authoritative commercial order aggregate | R:customers,payments,order_dependencies,audit_events | A:order_number,OrderRepository,OrderService,POST_/orders | S:Order state transitions and their ledger effects must commit in one transaction; completed orders are retained rather than deleted
(样例来自 testdata/volumes/database-quality/aoci.database.txt)
五步打通:从声明数据源到表级认知 ✅
整个流程命令都很直白,网络访问只发生在显式数据库命令中,其余步骤全部离线:
1. 声明一个数据库源(不存任何密码)
aoci --repo . database source add \
--source-id primary \
--engine postgresql \
--database-name app \
--namespace public
省略 --credential-env 时,AOCI 会从 source-id 派生环境变量名(primary → AOCI_DB_PRIMARY_DSN)。配置里只保存这个引用名,连接串由 DBA 在 AOCI 进程之外通过环境变量提供。用只读预检确认凭据是否就绪:
aoci --repo . database source access --source primary --json
2. 采集只读结构证据(Snapshot)
aoci --repo . database snapshot --source primary --json
这一步读取的只是系统目录(information_schema / pg_catalog 等),记录基表、列、主键/外键、索引、分区等结构事实,并生成内容寻址的 table_evidence_sha256 指纹。
3. 显式接受证据基线
aoci --repo . database baseline accept --source primary \
--snapshot-sha <source_snapshot_sha256> --json
4. 开启 Database Cognition Volume
对已对齐的 Code-only Volumes 项目执行窄范围 Bootstrap,只添加 Database 描述符、标记型 aoci.database.txt 和基线绑定,不触碰任何代码内容:
aoci --repo . database cognition bootstrap
aoci --repo . database cognition status --json
5. 让 Agent 写表级 FRAS
之后走标准的 MCP 维护循环:Agent 调用 aoci_maintain 获取确定性的候选页面(含完整 Table Evidence、字典规则和合法示例),阅读证据后为每张表写出完整条目,再用 aoci_update_entry 提交整批候选。每页候选都绑定 Volume 预镜像与表证据 SHA,写入走既有的 CAS/原子写/基线/恢复管线。
三大引擎支持情况一览 🗄️
| 引擎 | 驱动 | v1 覆盖范围与限制 |
|---|---|---|
| PostgreSQL | jackc/pgx/v5 |
基表 + 分区表;JSONB、serial、identity、生成列、表达式/部分/包含索引、分区方法/边界 |
| MySQL | go-sql-driver/mysql |
MySQL 8.0+;--namespace 必须等于 --database-name;覆盖 auto_increment、前缀/降序/不可见索引、分区定义 |
| openGauss | 打过评审补丁的 openGauss-connector-go-pq v1.0.8(见 third_party/openGauss-connector-go-pq) |
仅限 6.0.5 LTS + A/PG 兼容模式的普通非分区基表;遇到分区、列存、MOT、视图等不支持特性会 fail-closed(报 unsupported_catalog_feature),绝不静默降级成 PostgreSQL 事实 |
三个驱动均为纯 Go 实现,支持 CGO_ENABLED=0。详细契约见 docs/database-evidence.md 与 docs/database-cognition-authoring.md。
安全边界:读什么、不读什么 🔒
AOCI-CODE 的数据边界非常克制,值得新手放心使用:
- 只读、单连接、可重复读事务;永不查询业务行,不 SELECT/COUNT 数据,不采样值,不读统计信息
- 零 DDL/DML:不执行 INSERT、UPDATE、DELETE、ALTER、CREATE、DROP、迁移
- 凭据不落盘:DSN、密码、主机、用户名永远不写入索引、证据、基线或日志;错误信息只暴露稳定错误码
- 离线治理:Maintain、status、候选校验与 Apply 全程不重连数据库
- 改名不猜测:表重命名报告为
removed+new,由人和模型决定认知工作,绝不自动"对齐" - openGauss 的 TCP 非回环连接强制
sslmode=verify-full+ TLS 1.2+,拒绝降级模式
采集器源码集中在 internal/dbevidence/,认知评估逻辑在 internal/dbcognition/。
认知状态体检:一眼看懂索引健康度 🩺
aoci database cognition status 会对每张表给出离线状态:
| 状态 | 含义 |
|---|---|
cognition_current |
条目、条目 SHA 与当前证据 SHA 一致,一切就绪 |
cognition_missing |
证据里有这张表,但 Volume 里还没有条目 |
cognition_stale |
绑定的证据身份与当前证据不一致(结构变了) |
cognition_unbaselined |
条目存在但缺少对应绑定 |
cognition_orphan |
当前证据里已没有这张表(停下待人工裁决,不会自动删除) |
结构漂移只会让受影响的表变 stale,其他表的指纹保持稳定——这让增量维护的成本非常低。
延伸阅读:官方文档与关键源码
- 入门与安装:docs/getting-started.md、docs/install.md
- 数据库认知创作契约:docs/database-cognition-authoring.md
- 数据库证据层说明:docs/database-evidence.md
- 认知 Volume 总体设计:docs/cognition-volumes.md
- 真实表证据样例:testdata/volumes/database-quality/aoci.database.txt
💡 一句话总结:先建好代码索引,再声明数据库源、采集证据、接受基线、Bootstrap 开启 Database Volume,Agent 就会把表结构和代码放进同一张"系统地图"——从此改表之前,Agent 已经知道哪张表是权威、哪条约束碰不得。
