SQL中列注释必须用COMMENT子句（MySQL/PostgreSQL建表或ALTER时）或COMMENT ON COLUMN（PostgreSQL唯一方式），而非注释符号或ORM文档，且需注意长度限制与查询系统表位置。
SQL 中给列加注释用 COMMENT，不是 COMMENT ON 或注释符号
mysql 8.0+ 和 postgresql 都支持直接在建表或修改列时用 comment 子句写说明，但很多人误以为要像 oracle 那样用 comment on column，或者干脆把注释写成 sql 注释（-- 或 /* */），这些都不进数据字典。
- MySQL 建表时：字段定义末尾加
COMMENT '用户手机号，脱敏存储' - MySQL 修改列：用
ALTER TABLE user ADD COLUMN phone VARCHAR(11) COMMENT '用户手机号，脱敏存储' - PostgreSQL 必须用
COMMENT ON COLUMN user.phone IS '用户手机号，脱敏存储'—— 这是唯一方式，不支持建表内写COMMENT - SQLite 不支持列级注释，只能靠外部文档或表注释凑合
生成数据字典时，只读 information_schema.COLUMNS.COMMENT 或 pg_description
工具或脚本扫出字段说明，靠的不是源码里的注释块，而是数据库系统表里存的 COMMENT 值。如果没显式写，这列就是 NULL 或空字符串，不会 fallback 到字段名拼音、类型描述之类“智能猜测”。
- MySQL 查法：
SELECT COLUMN_NAME, COLUMN_COMMENT FROM information_schema.COLUMNS WHERE TABLE_NAME = 'user' AND TABLE_SCHEMA = 'mydb' - PostgreSQL 查法：
SELECT a.attname AS column_name, d.description AS column_comment FROM pg_attribute a JOIN pg_class c ON a.attrelid = c.oid JOIN pg_namespace n ON c.relnamespace = n.oid LEFT JOIN pg_description d ON d.objoid = c.oid AND d.objsubid = a.attnum WHERE c.relname = 'user' AND n.nspname = 'public' AND a.attnum > 0 AND NOT a.attisdropped - 别依赖 ORM 的模型 docstring —— Django 的
help_text、SQLAlchemy 的doc属性都不会自动同步到 DB 的COMMENT字段
COMMENT 内容长度有限制，超长会被截断且无警告
MySQL 8.0 最大支持 1024 字符，PostgreSQL 是 1024 字节（非字符），超出部分静默丢弃。你看到的 COLUMN_COMMENT 可能是半截话，尤其复制粘贴带 emoji 或全角空格时更容易踩中边界。
- 避免写长段落，优先用短语：用
'创建时间，UTC 时区'，别写'该字段记录用户首次注册的时间戳，采用协调世界时 UTC 标准，不带本地时区偏移' - 不要在
COMMENT里放 SQL 特殊字符如单引号、反斜杠，MySQL 会报语法错误；PostgreSQL 要手动转义单引号（写两个''） - 中文项目建议统一用 UTF8MB4，否则 MySQL 可能把某些生僻字算作多字节，提前触达长度上限
字段注释 ≠ 表注释，COMMENT ON TABLE 和 COMMENT ON COLUMN 是两套独立存储
有人给表加了 COMMENT 就以为字段也有说明，结果导出的数据字典里字段备注全是空。系统表里这两类注释存在不同字段或不同关联方式，查的时候漏掉就什么也捞不到。
- MySQL：表注释在
information_schema.TABLES.TABLE_COMMENT，列注释在information_schema.COLUMNS.COLUMN_COMMENT，二者完全不互通 - PostgreSQL：表注释存在
pg_description里objsubid = 0的行，列注释是同一张表里objsubid > 0的行，查的时候必须带上这个条件过滤 - 生成数据字典脚本如果只查表注释，字段那一栏就会集体失联 —— 这是最常被忽略的结构性遗漏
字段注释一旦没写进系统表，后续补救就得连改结构带刷数据字典模板，比一开始写清楚麻烦得多。真正卡住人的往往不是语法，而是查哪张表、关联哪个字段、长度怎么算。
