本文详解如何在 SQLModel 中正确声明 timezone-aware 的 datetime 字段，避免因混用 offset-naive 与 offset-aware datetime 导致的 TypeError: can't subtract offset-naive and offset-aware datetimes 错误。核心在于显式配置 SQLAlchemy 底层列类型。
本文详解如何在 sqlmodel 中正确声明 timezone-aware 的 datetime 字段，避免因混用 offset-naive 与 offset-aware datetime 导致的 `typeerror: can't subtract offset-naive and offset-aware datetimes` 错误。核心在于显式配置 sqlalchemy 底层列类型。
在使用 SQLModel（基于 SQLAlchemy 和 Pydantic）构建 PostgreSQL 应用时，一个常见但易被忽视的问题是：Python 的 datetime 类型默认不携带时区信息（即 offset-naive），而 PostgreSQL 的 TIMESTAMP WITH TIME ZONE（timestamptz）要求时区感知值。当开发者在 Field 中使用 datetime.now(timezone.utc) 作为 default_factory，却未同步告知数据库该字段应存储带时区的时间戳时，SQLAlchemy 的异步驱动（如 asyncpg）会在序列化过程中尝试对齐时间精度，从而触发 TypeError —— 正如错误堆栈所示：
TypeError: can't subtract offset-naive and offset-aware datetimes
根本原因在于：SQLModel 默认将 datetime 类型映射为 sa.DateTime(timezone=False)（即 TIMESTAMP WITHOUT TIME ZONE），而你传入的是 tzinfo=timezone.utc 的实例，导致类型契约冲突。
✅ 正确解法是通过 sa_column 显式覆盖底层 SQLAlchemy 列定义，强制使用带时区支持的类型，并确保 Python 层与数据库层语义一致：
from datetime import datetime, timezone
import uuid
from sqlmodel import Field, SQLModel
from sqlalchemy import DateTime # 注意：直接导入 SQLAlchemy 的 DateTime
class UserBase(SQLModel):
id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
phone_number: str = Field(max_length=255)
phone_prefix: str = Field(max_length=10)
class User(UserBase, table=True):
__table_args__ = (
UniqueConstraint("phone_number", "phone_prefix", name="phone_number_phone_prefix_constraint"),
)
registered_at: datetime = Field(
sa_column=DateTime(timezone=True), # ✅ 关键：启用时区支持
default_factory=lambda: datetime.now(timezone.utc)
)
# 注意：无需额外 nullable=False — Field 默认非空；若需允许 NULL，可加 nullable=True 并移除 default_factory? 重要说明与最佳实践：
- sa_column=DateTime(timezone=True) 等价于 sa.Column(sa.DateTime(timezone=True), nullable=False)，SQLModel 会自动处理 nullable 行为（有 default_factory 或 default 时设为 NOT NULL）；
- PostgreSQL 将该列物理存储为 timestamptz，并自动将输入时间标准化为 UTC（无论客户端传入 +08:00 还是 UTC）；
- 若后续需查询本地时区时间，应在应用层转换（如 dt.astimezone(tz=your_local_tz)），切勿依赖数据库 AT TIME ZONE 做业务逻辑转换，以保持时区处理的一致性与可测试性；
- 避免混用：不要在一个模型中部分字段用 timezone=True、部分用 timezone=False；统一采用 timezone=True + datetime.now(timezone.utc) 是现代 Web 应用的推荐模式；
- 测试验证：插入后可通过 SELECT pg_typeof(registered_at) 确认列为 timestamp with time zone。
总结：SQLModel 不自动推断 datetime 是否带时区，必须通过 sa_column 显式声明 DateTime(timezone=True)。这一配置不仅解决当前 TypeError，更是保障分布式系统中时间一致性、审计合规性与跨时区用户体验的基础设计决策。
