在FastAPI+PostgreSQL中用SqlModel定义自增主键的最佳实践

我在FastAPI + PostgreSQL应用中使用Tiangolo的SqlModel库，目前定义主键的方式如下：

class SomeSchema(SqlModel, table=True):
    __tablename__ = 'some_schema'
    id: Optional[int] = Field(default=None, primary_key=True)

采用这种写法时，收到了SQLAlchemy的警告：

SAWarning: Column 'some_schema.id' is marked as a member of the primary key for table 'some_schema', but has no Python-side or server-side default generator indicated, nor does it indicate 'autoincrement=True' or 'nullable=True', and no explicit value is passed. Primary key columns typically may not store NULL. Note that as of SQLAlchemy 1.1, 'autoincrement=True' must be indicated explicitly for composite (e.g. multicolumn) primary keys if AUTO_INCREMENT/SERIAL/IDENTITY behavior is expected for one of the columns in the primary key. CREATE TABLE statements are impacted by this change as well on most backends.

SqlModel的Field对象不像SQLAlchemy的Column那样有autoincrement参数，而且官方文档也没提自增ID列的相关内容，想问下用这个库定义id列为自增主键的最佳实践是什么？

针对PostgreSQL环境，有两种可靠的实现方式：

方式一：利用SqlModel隐式自增逻辑 #

SqlModel基于SQLAlchemy实现，对于单字段主键、类型为int且default=None的场景，会自动为PostgreSQL生成SERIAL类型（自增序列）。只需补充nullable=False即可消除警告：

from sqlmodel import Field, SqlModel, Optional

class SomeSchema(SqlModel, table=True):
    __tablename__ = 'some_schema'
    id: Optional[int] = Field(default=None, primary_key=True, nullable=False)

nullable=False明确告知SQLAlchemy该列不允许为空，同时SqlModel会自动处理自增逻辑，无需额外配置。

方式二：显式使用PostgreSQL IDENTITY类型（推荐） #

如果想使用PostgreSQL现代标准的自增机制，可通过sa_column_kwargs传递SQLAlchemy底层配置，指定autoincrement=True：

from sqlmodel import Field, SqlModel, Optional

class SomeSchema(SqlModel, table=True):
    __tablename__ = 'some_schema'
    id: Optional[int] = Field(
        default=None,
        primary_key=True,
        nullable=False,
        sa_column_kwargs={"autoincrement": True}
    )

或者直接指定PostgreSQL方言的IDENTITY类型，适配多数据库场景：

from sqlmodel import Field, SqlModel, Optional
from sqlalchemy.dialects.postgresql import INTEGER

class SomeSchema(SqlModel, table=True):
    __tablename__ = 'some_schema'
    id: Optional[int] = Field(
        default=None,
        primary_key=True,
        nullable=False,
        sa_column=INTEGER().with_variant(INTEGER, "sqlite"),
        sa_column_kwargs={"autoincrement": True}
    )

这种方式会生成PostgreSQL标准的GENERATED AS IDENTITY语法，比传统SERIAL更符合现代数据库最佳实践。

核心注意事项 #

• 必须保持id的类型为Optional[int]且default=None，让SqlModel识别该值由数据库自动生成。
• nullable=False是必填项，主键列本身不允许为空，这能直接消除警告中的nullable相关提示。
• 若使用复合主键，必须在需要自增的字段上通过sa_column_kwargs显式指定autoincrement=True，否则会触发SQLAlchemy警告。

内容的提问来源于stack exchange，提问作者muad-dweeb