Alembic 的 autogenerate 默认不会从 SQLAlchemy 关系（relationship）中推导数据库外键，必须显式声明 ForeignKey 列；本文详解正确建模方式、配置要点及常见误区。
alembic 的 `autogenerate` 默认不会从 sqlalchemy 关系（`relationship`）中推导数据库外键，必须显式声明 `foreignkey` 列；本文详解正确建模方式、配置要点及常见误区。
在使用 SQLAlchemy 2.0+ 声明式映射（Declarative Base）配合 Alembic 进行数据库迁移时，一个常见误解是：只要定义了 relationship()，Alembic 就能自动生成对应的数据库外键约束（FOREIGN KEY）。但事实并非如此——relationship 仅定义 Python 层的对象关联逻辑，不等价于数据库层面的外键约束。Alembic 的 autogenerate 功能依赖于 SQLAlchemy 元数据（MetaData）中实际存在的 ForeignKey 对象，而非 relationship 的存在。
要使 Alembic 正确生成含外键的迁移脚本，关键在于：在模型中显式声明 ForeignKey 列。以下为修正后的标准写法（以一对多关系为例）：
from typing import List
from sqlalchemy import String, ForeignKey
from sqlalchemy.orm import DeclarativeBase, mapped_column, Mapped, relationship
class Base(DeclarativeBase):
pass
class DBUnitCategory(Base):
__tablename__ = 'unit_category'
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(String(20))
# 反向关系：指向 DBUnit 的列表（仅 Python 层）
units: Mapped[List["DBUnit"]] = relationship(back_populates="category")
class DBUnit(Base):
__tablename__ = 'unit'
id: Mapped[int] = mapped_column(primary_key=True)
name: Mapped[str] = mapped_column(String(12))
# ✅ 关键：显式声明外键列（数据库约束来源）
category_id: Mapped[int] = mapped_column(ForeignKey("unit_category.id"))
# ✅ 关联字段：引用另一端的 relationship 名称（非列名）
category: Mapped[DBUnitCategory] = relationship(back_populates="units")
⚠️ 注意事项：
ForeignKey("unit_category.id")中的字符串必须与目标表名和列名完全一致（区分大小写，且不含 schema 前缀，除非使用schema=参数）；back_populates的值需严格匹配对方模型中relationship的变量名（如units/category），而非列名（如category_id）；- 若使用 SQLite，确保
sqlalchemy.url配置中启用了foreign_keys=ON（例如：sqlite:///app.db?check_same_thread=False&foreign_keys=ON），否则外键约束虽生成但不会生效；- 运行
alembic revision --autogenerate -m "init"前，请确认env.py中target_metadata已正确定义为你的Base.metadata。
修正后执行自动迁移，upgrade() 函数将包含完整的外键定义：
def upgrade() -> None:
op.create_table('unit_category',
sa.Column('id', sa.Integer(), nullable=False),
sa.Column('name', sa.String(length=20), nullable=False),
sa.PrimaryKeyConstraint('id')
)
op.create_table('unit',
sa.Column('id', sa.Integer(), nullable=False),
sa.Column('name', sa.String(length=12), nullable=False),
sa.Column('category_id', sa.Integer(), nullable=False),
sa.ForeignKeyConstraint(['category_id'], ['unit_category.id']), # ✅ 自动生成
sa.PrimaryKeyConstraint('id')
)
总结：Alembic 自动化能力基于数据库元数据而非 ORM 语义。关系（relationship）负责对象导航，外键（ForeignKey）负责数据完整性——二者需协同定义，缺一不可。遵循“先列后关系”原则（即先定义带 ForeignKey 的列，再定义 relationship），即可确保 autogenerate 输出完整、可部署的迁移脚本。
