如何在SQLAlchemy的Alembic中修改时区为UTC？

错误原因 #

你遇到的Can't locate timezone: UTC报错，本质是因为SQLite数据库本身不支持时区数据库，Alembic尝试加载时区数据时无法找到对应资源，所以无论填什么时区值都会报错。从日志里的Context impl SQLiteImpl也能确认你当前用的是SQLite。

解决步骤 #

1. 调整alembic.ini配置 #

直接注释或删除alembic.ini里的timezone = UTC配置行，因为SQLite不支持这个参数，留着只会触发报错。

2. 在SQLAlchemy层面强制UTC时区 #

虽然SQLite本身不支持时区，但可以通过SQLAlchemy的配置确保所有时间操作都使用UTC：

• 创建引擎时，添加timezone=True参数：

from sqlalchemy import create_engine

engine = create_engine(
    "sqlite:///./test.db",
    connect_args={"check_same_thread": False},
    timezone=True  # 强制使用UTC
)

• 模型里的日期字段使用DateTime(timezone=True)类型：

from sqlalchemy import DateTime
from sqlalchemy.orm import Mapped, mapped_column
from datetime import datetime

class YourModel(Base):
    __tablename__ = "your_table"
    id: Mapped[int] = mapped_column(primary_key=True)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=datetime.utcnow)

3. 配置FastAPI全局UTC #

在FastAPI的Pydantic配置里设置默认时区为UTC，确保请求/响应的时间都以UTC处理：

from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict

app = FastAPI()

# 全局Pydantic配置
class Base(BaseModel):
    model_config = ConfigDict(timezone="UTC")

4. 调整Alembic的env.py（可选） #

如果需要迁移脚本里的时间相关操作也统一用UTC逻辑，可以在env.py的run_migrations_online函数中添加以下配置：

def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
        poolclass=pool.NullPool,
    )

    with connectable.connect() as connection:
        # 给SQLite连接设置UTC逻辑
        connection.execute("PRAGMA timezone = 'UTC';")
        connection.commit()
        context.configure(
            connection=connection, target_metadata=target_metadata
        )

        with context.begin_transaction():
            context.run_migrations()

这样就能确保整个FastAPI应用和数据库操作都统一使用UTC时区，同时避免Alembic的时区报错。

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