SQLModel如何为表添加注释并同步至SQL数据库？

SQLModel 本身没有原生提供直接配置表/字段注释的API，但由于它基于 SQLAlchemy 构建，我们可以借助 SQLAlchemy 的底层能力实现注释同步到数据库 Schema 的需求，具体有两种常用方式：

1. 利用 SQLAlchemy 原生参数（推荐） #

通过模型类的 __table_args__ 配置表注释，字段则通过 Field 的 sa_column_kwargs 参数传递 SQLAlchemy 列的注释属性，这种方式会在创建表时自动生成带注释的 DDL 语句。

示例代码：

from sqlmodel import SQLModel, Field

class User(SQLModel, table=True):
    # 表级注释
    __table_args__ = {"comment": "用户信息表，存储系统所有用户的基础数据"}
    
    # 字段级注释
    id: int = Field(
        default=None, 
        primary_key=True, 
        sa_column_kwargs={"comment": "用户唯一标识ID"}
    )
    username: str = Field(
        max_length=50, 
        sa_column_kwargs={"comment": "用户登录账号"}
    )
    email: str = Field(
        max_length=100, 
        sa_column_kwargs={"comment": "用户邮箱"}
    )

执行 SQLModel.metadata.create_all(engine) 时，SQLAlchemy 会根据数据库类型自动生成对应注释语法的 CREATE TABLE 语句，比如 MySQL 会直接在表和字段后追加 COMMENT 子句，PostgreSQL 会生成 COMMENT ON TABLE/COMMENT ON COLUMN 语句。

2. 自定义 DDL 语句（复杂场景适配） #

如果需要更灵活的注释修改逻辑，可以在表创建完成后，手动执行 ALTER 类的 DDL 语句添加注释，适合已有表的注释更新场景：

示例代码（以 MySQL 为例）：

from sqlmodel import SQLModel, create_engine
from sqlalchemy import DDL

engine = create_engine("mysql+pymysql://user:password@localhost/dbname")

# 先创建基础表结构
SQLModel.metadata.create_all(engine)

# 手动执行DDL添加注释
with engine.connect() as conn:
    # 添加表注释
    conn.execute(DDL("ALTER TABLE user COMMENT '用户信息表，存储系统所有用户的基础数据'"))
    # 添加字段注释
    conn.execute(DDL("ALTER TABLE user MODIFY COLUMN id INT COMMENT '用户唯一标识ID'"))
    conn.execute(DDL("ALTER TABLE user MODIFY COLUMN username VARCHAR(50) COMMENT '用户登录账号'"))
    conn.commit()

注意事项 #

• 不同数据库的注释语法存在差异，第一种方式会由 SQLAlchemy 自动适配，兼容性更强；
• SQLite 对表/字段注释的支持有限，部分数据库管理工具可能无法显示注释，但底层会存储该信息。

内容的提问来源于stack exchange，提问作者user11696358