Alembic 1.8生成外键缺失INITIALLY IMMEDIATE配置的解决方法

SQLAlchemy 1.4 对Column内嵌的快捷ForeignKey定义支持有限：

• 仅传入deferrable=True时，PostgreSQL方言的DDL编译器只会输出DEFERRABLE关键字，不会读取传入的initially参数拼接后续配置
• Alembic 1.8的自动生成逻辑同样不会识别内嵌在Column里的外键initially参数，渲染迁移脚本时会直接丢弃该配置

模型定义层（推荐写法） #

不要把外键约束参数全部写在Column内嵌的ForeignKey快捷定义里，改用表级ForeignKeyConstraint声明，所有约束参数都能被SQLAlchemy和Alembic正确识别透传。

Core风格表定义写法：

from sqlalchemy import Table, Column, BigInteger, MetaData, ForeignKeyConstraint

metadata = MetaData()

auth_user_groups = Table(
    "auth_user_groups",
    metadata,
    Column("id", BigInteger, primary_key=True),
    Column("group_id", BigInteger, index=True, nullable=False),
    ForeignKeyConstraint(
        ["group_id"],
        ["auth_group.id"],
        onupdate="CASCADE",
        ondelete="CASCADE",
        deferrable=True,
        initially="IMMEDIATE",
        name="auth_user_groups_group_id_fkey"
    )
)

Declarative声明式模型写法，约束放在__table_args__中：

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy import Column, BigInteger, ForeignKeyConstraint

class Base(DeclarativeBase):
    pass

class AuthUserGroups(Base):
    __tablename__ = "auth_user_groups"
    id = Column(BigInteger, primary_key=True)
    group_id = Column(BigInteger, index=True, nullable=False)

    __table_args__ = (
        ForeignKeyConstraint(
            ["group_id"],
            ["auth_group.id"],
            onupdate="CASCADE",
            ondelete="CASCADE",
            deferrable=True,
            initially="IMMEDIATE",
            name="auth_user_groups_group_id_fkey"
        ),
    )

Alembic迁移脚本修正 #

如果是已经自动生成的迁移文件，直接在create_foreign_key调用中补全参数即可：

def upgrade():
    op.create_foreign_key(
        "auth_user_groups_group_id_fkey",
        "auth_user_groups",
        "auth_group",
        ["group_id"],
        ["id"],
        onupdate="CASCADE",
        ondelete="CASCADE",
        deferrable=True,
        initially="IMMEDIATE"
    )

配置完成后输出的DDL会符合预期：

CONSTRAINT auth_user_groups_group_id_fkey FOREIGN KEY (group_id)
    REFERENCES public.auth_group (id) MATCH SIMPLE
    ON UPDATE CASCADE
    ON DELETE CASCADE
    DEFERRABLE INITIALLY IMMEDIATE

补充说明：PostgreSQL中如果只声明DEFERRABLE不指定INITIALLY属性，部分版本会默认采用INITIALLY DEFERRED行为（即约束检查推迟到事务提交时），和INITIALLY IMMEDIATE（默认语句执行完立刻检查，仅手动设置时才延迟）的行为有差异，生产环境建议显式声明避免逻辑异常。

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