MySQL表级注释需在CREATE TABLE或ALTER TABLE时通过COMMENT子句添加，不支持单独SET；PostgreSQL则必须用COMMENT ON TABLE命令，且IS不可省略。

MySQL 里用 COMMENT 给表加注释，不是字段注释

表级注释只能在建表时或修改表结构时通过 comment 子句写入，不能像字段那样单独“添加”。很多人误以为能像 alter table ... modify column 那样单独更新注释，其实不行。

常见错误现象：ALTER TABLE t1 SET COMMENT = 'xxx' 报错 —— MySQL 不支持这种语法；或者写了 COMMENT 却发现没生效，大概率是忘了加引号、用了中文引号，或注释超长（MySQL 5.7+ 限制 2048 字符）。

• 建表时直接加：CREATE TABLE t1 (id INT) COMMENT='用户主表';
• 修改已有表：ALTER TABLE t1 COMMENT='用户主表（含软删除标记）';
• 注释内容必须是字符串字面量，单引号或双引号都行，但不能用反引号
• 空格、换行、中文都合法，但别塞 SQL 注释（如 -- 或 /* */），会被当作文本存进去

PostgreSQL 怎么给表加注释：用 COMMENT ON TABLE

PostgreSQL 不支持建表语句里直接写表注释，必须用独立的 COMMENT ON TABLE 命令。这是和 MySQL 最容易混淆的一点 —— 写法不同，且不支持在 CREATE TABLE 后面跟 COMMENT。

使用场景：自动化脚本里如果混用 MySQL 和 PG 的 DDL，这里极易出错；另外，PG 的注释会持久化到系统视图 pg_tables 和 pg_description，查的时候得知道从哪取。

• 正确写法：COMMENT ON TABLE users IS '核心用户信息，含注册时间与状态';
• 要删注释？没有直接命令，得用空字符串覆盖：COMMENT ON TABLE users IS '';
• 注意 IS 关键字不能省，也不能写成 = 或 :
• 表名要带 schema（如 public.users），否则默认找当前 search_path 下的表

注释能被哪些工具读出来？别指望 ORM 自动映射

大多数 ORM（比如 SQLAlchemy、MyBatis、TypeORM）不会把表注释自动变成类 docstring 或字段描述。它们只解析结构，不主动查 information_schema 或 pg_description。所以别幻想加了注释，Swagger 或文档生成器就能自动显示。

性能影响几乎为零 —— 注释存在系统表里，不参与查询执行计划；但兼容性要注意：SQLite 不支持表级注释，SQL Server 用的是扩展属性（sp_addextendedproperty），和 MySQL/PG 完全不兼容。

• 想让注释可见，得手动查：SELECT table_comment FROM information_schema.tables WHERE table_name = 't1';（MySQL）
• PG 查：SELECT obj_description('users'::regclass);
• Navicat、DBeaver 这类 GUI 工具能显示，但前提是连接后主动刷新元数据
• 有些 CI/CD 工具（如 Liquibase）支持导出注释，但需显式配置 includeCatalog=true 类参数

为什么改了注释，某些客户端还是看不到？

不是注释没生效，而是客户端缓存了元数据，或者根本没去查注释字段。比如 MySQL Workbench 在“Table Inspector”里显示注释，但得右键刷新；而很多轻量 CLI 工具（如 mysql -e "DESCRIBE t1"）压根不展示 Comment 列。

最容易被忽略的地方：注释内容里的特殊字符（比如单引号、反斜杠）没转义，导致生成的 DDL 脚本执行失败；还有就是开发本地用 MySQL 8.0，测试环境是 5.6，后者对注释长度更敏感，超长会被截断且不报错。

• 验证是否写入成功：SHOW CREATE TABLE t1; 看输出末尾有没有 COMMENT='...'
• 跨版本迁移时，先用 mysqldump --no-create-info 检查 dump 文件里是否保留了注释
• 如果用 Flyway/Liquibase 管理变更，确保 COMMENT 语句放在 ALTER TABLE 之后，且不和其他 DDL 合并在一行