SQLAlchemy声明式数据类映射：如何创建非必填列？

要解决你的问题，核心是确保数据类字段同时绑定SQLAlchemy的Column（或2.0版本的mapped_column），并正确结合Optional类型标注与默认值配置，以下是具体实现方式：

正确实现示例（兼容SQLAlchemy 1.x和2.x） #

1. 基础配置 #

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from dataclasses import dataclass, Optional

# 数据库连接配置
engine = create_engine("sqlite:///test.db")
Base = declarative_base()

2. 带可选字段的映射类 #

@dataclass
class TestModel(Base):
    __tablename__ = "test_table"
    
    # 主键字段
    id: int = Column(Integer, primary_key=True, autoincrement=True)
    # 必填字段（无默认值，实例化时必须传参）
    int_var: int = Column(Integer)
    str_var: str = Column(String(50))
    # 可选字段：Python层面默认值，实例化时可省略，数据库列会生成
    optional_str: Optional[str] = Column(String(50), default=None)
    # 可选字段：数据库层面默认值（插入时由数据库填充）
    optional_int: Optional[int] = Column(Integer, server_default="0")
    # 可选字段：同时设置Python和数据库默认值（保持一致即可）
    default_field: Optional[str] = Column(String(50), default="default_val", server_default="'default_val'")

3. 实例化方式 #

# 实例化时可省略所有可选字段
instance1 = TestModel(int_var=10, str_var="hello")
# 也可主动传入可选字段的值
instance2 = TestModel(int_var=20, str_var="world", optional_str="custom")

常见错误解析 #

错误1：仅设置数据类默认值，未绑定Column #

@dataclass
class WrongModel(Base):
    __tablename__ = "wrong_table"
    id: int = Column(Integer, primary_key=True)
    # 此字段不会生成数据库列，仅为数据类的普通字段
    optional_var: Optional[str] = None

SQLAlchemy只会识别赋值为Column对象的字段作为表列，普通数据类字段不会被映射到数据库。

错误2：仅标注Optional，未设置默认值 #

@dataclass
class WrongModel2(Base):
    __tablename__ = "wrong_table2"
    id: int = Column(Integer, primary_key=True)
    # 实例化时必须传参，否则数据类会报错
    optional_var: Optional[str] = Column(String(50))

虽然SQLAlchemy的Column允许NULL，但数据类本身要求所有无默认值的字段必须在实例化时传入参数，因此需要配合default或server_default配置。

SQLAlchemy 2.x 推荐写法（使用Mapped和mapped_column） #

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from dataclasses import dataclass, Optional

class Base(DeclarativeBase):
    pass

@dataclass
class TestModelV2(Base):
    __tablename__ = "test_table_v2"
    
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    int_var: Mapped[int] = mapped_column(Integer)
    str_var: Mapped[str] = mapped_column(String(50))
    # 可选字段配置更清晰
    optional_str: Mapped[Optional[str]] = mapped_column(String(50), default=None)
    optional_int: Mapped[Optional[int]] = mapped_column(Integer, server_default="0")

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