MySQL字段注释失效主因是DDL工具过滤COMMENT或版本兼容问题；PostgreSQL必须用COMMENT ON COLUMN单独执行；注释需转义单引号、禁换行、限长度、与代码一致，并全程校验。
MySQL 中用 COMMENT 写字段注释，但生产库没生效
常见现象是开发在建表 sql 里写了 comment '用户昵称'，本地执行没问题，但上线后 show create table 一看，注释全没了。根本原因往往是 ddl 脚本生成工具（比如某些 orm、数据库同步工具或自研脚本）默认过滤或忽略 comment 子句，或者执行时用了不支持的 mysql 版本（comment 在早期 5.0 之前有兼容问题，但现在基本不是主因）。
实操建议：
- 检查生成脚本是否保留了
COMMENT—— 直接打开生成的.sql文件，搜COMMENT关键字，确认它出现在每个CREATE TABLE或ALTER TABLE ... MODIFY COLUMN语句中 - 避免用
mysqldump --no-create-info或导出结构时不加--skip-comments（这个参数实际是「跳过注释」，名字反直觉） - 如果用 Flyway/Liquibase，确认
sql迁移文件里写的是原生 DDL，而不是靠它们的 Java API 自动生成 —— 后者对COMMENT支持不稳定
PostgreSQL 字段注释必须用 COMMENT ON COLUMN 单独执行
和 MySQL 不同，PostgreSQL 不允许在 CREATE TABLE 或 ALTER TABLE ... ADD COLUMN 里直接写 COMMENT。你写进去也不会报错，但注释不会存到系统表里，\d 表名 看不到，pg_description 也查不到。
实操建议：
- 建表语句和注释语句必须拆开：先
CREATE TABLE，再用独立的COMMENT ON COLUMN schema.table.column IS 'xxx'; - 批量生成时，别依赖“一键导出全部 DDL”功能 —— pgAdmin 或
pg_dump -s默认不导出注释，得加--inserts --column-inserts配合额外脚本提取pg_description - 注意权限：执行
COMMENT ON需要目标表的OWNER权限，普通SELECT用户不行；CI/CD 执行时容易卡在这步
DDL 脚本执行前必须校验注释是否被意外截断
注释内容含单引号、换行、中文括号或 emoji 时，很多脚本生成器会做不安全的字符串拼接，导致 SQL 语法错误或注释被截断。典型错误信息：ERROR 1064 (42000): You have an error in your SQL syntax，位置往往卡在 COMMENT 后面。
实操建议：
- 所有注释内容必须用单引号包裹，并对内部单引号做转义（
'O''Reilly'），不要依赖自动 escape 工具 —— 很多 Python 的str.replace("'", "''")只处理单层，嵌套就崩 - 禁止在注释里换行；如需多行说明，改用空格+分号分隔，例如
'状态码;0-待审核;1-已通过' - 上线前用
mysql -e "source xxx.sql"或psql -f xxx.sql在测试库跑一遍，再立刻查information_schema.COLUMNS.COLUMN_COMMENT（MySQL）或pg_description（PG），确认值完全一致
同步注释 ≠ 同步业务逻辑，别让 DDL 脚本承担文档职责
有人把字段注释当需求文档用，写满“该字段由风控系统调用，每小时更新一次，不可为空”，结果上线后发现 DBA 把注释长度限制设成 1024 字节，超长部分被静默截断；或者某次重建从备份恢复，注释全丢了也没人发现。
实操建议：
- 注释只放最简必要信息：字段用途（非流程）、单位（如
'毫秒'）、枚举含义（如'0-失败,1-成功'），别塞逻辑规则 - 注释内容必须和代码里的常量/枚举定义保持一致 —— 比如 Java 里
public static final int STATUS_SUCCESS = 1;，注释就得写'1-成功'，不能写'1-已完成' - 定期用脚本比对开发库和生产库的
COLUMN_COMMENT差异（可用SELECT ... FROM information_schema.COLUMNS导出后 diff），别等上线才发现漏同步
注释同步这件事，表面是 SQL 语法问题，实际是协作链路断点问题 —— 开发写完不验证、DBA 执行不反馈、QA 不查元数据，三处任一掉链子，注释就永远停在本地 IDE 里。
