99%开发者不用COMMENT, 未来将是数据库 AI 化的必选项

本期播客

过去被99%的开发者忽视的COMMENT, 未来是数据库智能化的必选项

“表建好了、索引加了、权限配了，为什么 AI 还是总写错 SQL？”
答案可能很残酷： 不是模型不够聪明，而是你的数据库从来没认真‘自我介绍’。

很多数据库管理员和架构师，把 COMMENT 当成“可有可无的注释”；很多应用开发者和数据库用户，把它当成“以后再补的文档”。但到了 AI 时代，这个被忽视了几十年的命令，正在从“锦上添花”变成“决定 AI 是否靠谱理解业务语义的基础设施”。PostgreSQL 官方文档明确说明，COMMENT 可以给数据库对象存储描述信息，且这些注释会进入系统目录 pg_description，也可以通过 psql \d 以及内置函数读取。换句话说， 这不是写给人看的装饰，而是数据库原生可查询的语义层。

过去，COMMENT 是“礼貌”；现在，COMMENT 是“生产力”

先说一个很多团队都没意识到的变化。

过去数据库的主要消费者是人：DBA、架构师、后端工程师、BI 工程师。即使表名起得一般、字段名有点缩写，团队里总有人知道 amt 是金额、biz_dt 是业务日期、flag 到底代表启用、删除还是风控命中。
但今天，数据库的消费者变了。除了人，还有一类越来越重要的“新同事”——AI 驱动的数据库助手、MCP Client、Text-to-SQL Agent、Copilot 工具链。

这些系统默认能看到什么？
无非是 schema、表名、字段名、主外键、约束。它们能推断结构，但推断不了业务意图。

例如：

• status 到底是订单状态、支付状态，还是物流状态？
• dt 是创建日期、记账日期，还是统计口径日期？
• is_valid 是业务有效、逻辑未删，还是风控审核通过？

这些信息，如果没有注释补足，AI 只能靠猜。
而一旦靠猜，生成 SQL 的“语法正确率”可能不低，但“业务正确率”会很难看。

这不是拍脑袋的判断。Text-to-SQL 领域近年的研究已经反复证明： schema linking —— 也就是把用户问题和数据库对象正确关联起来——是 SQL 生成质量的核心瓶颈之一；补充更丰富的 schema 描述、表和字段说明，会显著改善结果。研究显示，包含 schema、表描述、列描述、主外键和示例查询等更完整元数据配置的方案，答案正确率可达到 84.5%，明显优于简化元数据方案；另有研究指出，数据库描述在 Text-to-SQL 中对桥接自然语言与数据库结构“至关重要”，自动生成描述也能继续提升 SQL 生成准确率。

所以结论很直接：AI 用库时代，COMMENT 不再是“文档意识”，而是“检索质量”和“生成质量”的输入变量。

第一性原理：AI 为什么离不开数据库注释？

把问题掰开看，本质上只有一句话：

SQL 生成不是纯语法问题，而是语义对齐问题。

数据库对象名解决的是“它叫什么”；
注释解决的是“它到底是什么、为什么存在、在什么业务口径下使用”。

这两者不是一个层级。

从第一性原理出发，任何一个 AI 想正确写 SQL，至少要完成三步：

1. 识别业务问题中的实体与指标
2. 映射到正确的表、字段和关系
3. 理解口径、边界条件和禁区

schema 名称最多解决第 2 步的一部分，真正决定第 1 步和第 3 步的，是语义信息。
而在 PostgreSQL 里，COMMENT 正好是最贴近数据库对象、最便于长期维护、最容易被工具链读取的语义载体。官方也明确说明，注释是数据库对象的可选描述，且直接存储在系统目录中，可被程序化读取。

这意味着什么？

意味着对于 DBA 和架构师 来说，COMMENT 不是“额外负担”，而是把业务语义内嵌进数据资产本体。
意味着对于应用开发者来说，COMMENT 不是“帮别人看懂”，而是在帮未来的自己、帮团队、帮 AI 减少误解成本。

为什么今天必须重视这件事？因为 PostgreSQL 已经不是小众数据库了

还有人会说：“这只是理想化说法，真有那么重要吗？”

重要。因为 PostgreSQL 早就不是少数专家使用的数据库。Stack Overflow 2024 开发者调查显示，PostgreSQL 以 49% 的使用率成为最流行的数据库，而且已经连续第二年位居第一。也就是说， 今天大量新系统、AI 增强系统、数据平台和业务后台，都在 PostgreSQL 之上建设。 当底座足够主流，一个原生能力是否被正确使用，就不再是局部优化，而会变成普遍性的工程分水岭。

说得再直白一点：

• 在“人写 SQL”的时代，注释缺失，代价是沟通成本；
• 在“AI 帮你写 SQL”的时代，注释缺失，代价是错误查询、口径偏差、权限误用、结果幻觉。

这两种代价，不在一个量级上。

DBA 和架构师最容易犯的错：把注释当成“开发自觉”

这是很多组织里的真问题。

数据库治理一谈到注释，常见说法是：

• “让开发自己补”
• “重要表再说”
• “上线后慢慢补”
• “有数据字典就够了”

这些说法听起来都合理，但放到 AI 时代，大多数都站不住。

因为外部数据字典、Wiki、Excel 口径表，最大的问题不是没有价值，而是离数据库对象太远：

• 更新不同步
• 检索不稳定
• AI 工具默认拿不到
• 人和机器都无法保证使用的是同一版本语义

而 PostgreSQL 的 COMMENT 恰恰相反：
它跟对象同生命周期，对象删了注释也一起删；对象改了，注释应该同步变更；而且它原生存在数据库目录中，可以被命令行、GUI、函数和程序统一读取。

所以对 DBA/架构师 来说，真正该做的不是“呼吁大家写注释”，而是把它提升成schema 设计规范、上线门槛和治理基线。

我的观点很明确：

没有注释的核心业务表，不应该被视为“完成设计”。
没有注释的关键字段，不应该被视为“完成交付”。

这不是形式主义，这是面向机器协作时代的最低语义成本控制。

应用开发者也别装无辜：AI 写错 SQL，很多锅其实该你背

另一个需要点破的事实是：
很多开发者一边抱怨 AI 查库不准，一边自己把字段命名成：

• val
• type
• remark
• ext
• status
• data
• flag

然后还不给任何 COMMENT。

这种数据库，别说 AI 了，三个月后的自己都未必看得懂。

应用开发者往往觉得，注释是 DBA 文档化的一部分；其实恰恰相反， 最懂字段业务含义的人，通常就是建这个表、写这段代码的人。 如果这个语义没有在建模时沉淀下来，后面再补，准确度和积极性都会迅速衰减。

所以开发者要接受一个现实：

在 AI 时代，写 DDL 不再只是在定义结构，也是在给机器提供上下文。

你今天少写的一句字段注释，明天很可能变成：

• AI 选错表
• 报表口径跑偏
• 联表条件错误
• 业务方拿到错误结论
• 你再花 2 小时解释“为什么这个字段不能这么用”

这不是“多写点文档”的问题，这是把一次性建模成本，换成反复返工成本。

真正有价值的 COMMENT，不是“中文翻译”，而是“业务约束说明”

这里还有一个误区必须纠正。

很多团队开始补注释后，写成这样：

• user_id: 用户ID
• status: 状态
• amount: 金额
• created_at: 创建时间

这类注释几乎没价值。因为字段名本身已经表达了 80%。

真正高质量的注释，应该补的是字段名没有表达出来的那 20% 关键语义，比如：

• 口径：实付金额 / 应付金额 / 含税 / 不含税
• 枚举：0=待支付，1=已支付，2=已退款
• 边界：仅记录成功交易，不含关闭订单
• 时间语义：业务发生时间，不是数据入库时间
• 主体范围：B端商户，不含个人用户
• 更新规则：仅首次写入，后续不变

这才是真正能帮助人，也帮助 AI 的注释。

好注释不是字段名的复读机，而是业务语义的压缩包。

条件成立时，我支持“强制 COMMENT 治理”；条件崩塌时，策略要调整

为了避免把观点说绝对，我们把前提讲清楚。

前提一：你的数据库会被多人协作使用

如果数据库只有单人维护、生命周期很短、业务极简单，那么系统性补注释的 ROI 可能没那么高。

前提二：数据库会被 BI、分析、Agent、MCP Client、自动化工具消费

如果数据库只做单应用后端存储，且永远不暴露给任何查询型工具，那么 COMMENT 的收益释放会慢一些。
但只要系统进入数据分析、运营查询、AI 助手、低代码报表场景，收益就会迅速放大。

前提三：你的命名规范不能完整表达业务语义

如果你们已经做到了极其严格的一致命名、清晰建模、完备枚举表和数据字典，注释的边际收益会下降。
但现实是，大多数组织做不到这一点。

所以我的判断是：

• 在大多数真实企业环境里，强制 COMMENT 规范是成立的。
• 只有在极小、极短、极简单的系统里，它才可能退化成“可选优化项”。

而一旦这些前提崩塌，比如团队治理能力很弱、历史包袱巨大、存量库根本补不动，那也不是放弃的理由，而应该转向另一条路径：

优先补核心表、核心字段、核心指标；再用 AI 辅助生成候选注释，人审后落库。

这条路同样成立。因为已有研究表明，在没有现成描述时，生成式 AI 自动生成数据库描述，本身就能带来 SQL 生成质量提升。

最现实的落地建议：别想着“一次补完”，先打 3 个点

如果你是 DBA 或架构师，我建议从这 3 件事开始：

第一，把 COMMENT 纳入 DDL 规范。
新表、新字段、新视图、新函数，原则上同步写注释；没有注释，不算完整交付。

第二，优先覆盖高频被问询对象。
不是全库平推，而是先补最常被查询、报表、排障、AI 工具调用的那些表和字段。

第三，建立“注释质量标准”。
要求注释写业务含义、枚举口径、统计边界，不接受“状态”“备注”“类型”这种空话。

如果你是应用开发者或数据库用户，我建议你做两件事：

一是把注释当成代码的一部分。
写表结构时一起写，而不是事后补。

二是优先为歧义字段写注释。
尤其是 status、type、flag、amount、dt、time、source、remark 这类“看着认识、其实最容易误解”的字段。

最后一刀：未来数据库竞争，不只是性能竞争，更是“可理解性竞争”

过去我们衡量数据库治理成熟度，看的是：

• 性能
• 可用性
• 安全性
• 可扩展性

这些当然仍然重要。
但在 AI 开始深度参与开发、分析和运维之后，还会新增一个维度：

可理解性。

谁的数据库更容易被 AI 正确理解，谁的组织就更容易把自然语言查询、自动 SQL 生成、智能数据助手、半自动运维真正跑起来。
而 PostgreSQL 早就给了这个能力的入口——COMMENT。它不新，却足够实用；它不花哨，却正好踩在 AI 时代的关键节点上。官方系统目录 pg_description 甚至一开始就包含了大量内建对象的描述，这本身就说明： PostgreSQL 从来不把“语义描述”当成无关紧要的装饰。

所以，别再把 COMMENT 当成“有空再写”的边角料。
它正在从数据库世界里最容易被忽视的功能，变成 AI 时代最值得补的基础能力之一。

一句话总结：
以前，COMMENT 是写给人看的说明书；
现在，COMMENT 更像是写给 AI 的“数据库提示词”。

你不给，AI 就只能猜。
而所有靠猜的系统，迟早都会付出代价。

你怎么看？
你所在的团队，会把 PostgreSQL COMMENT 纳入建模和上线规范吗？还是你认为“命名规范 + 外部文档”已经足够？欢迎在评论区聊聊。