本文详解 SQLAlchemy 中 ON DELETE CASCADE 失效的常见误区：外键定义位置错误导致级联方向反向，明确指出级联必须定义在被引用方（子表）上，而非引用方（父表），并提供可运行的修正代码与关键配置验证步骤。
本文详解 sqlalchemy 中 `on delete cascade` 失效的常见误区：外键定义位置错误导致级联方向反向，明确指出级联必须定义在被引用方（子表）上，而非引用方（父表），并提供可运行的修正代码与关键配置验证步骤。
在使用 SQLAlchemy（配合 SQLite + aiosqlite）时，许多开发者会误以为只要在 ForeignKey 中声明 ondelete='CASCADE'，就能实现“删除主表记录时自动删除关联子表记录”。但实际执行 DELETE FROM accounts 时，日志仅显示 Accounts 表被删，Emails 表无任何变动——这并非 SQLAlchemy 或数据库驱动 Bug，而是外键级联方向理解错误所致。
? 核心原理：级联是“向下流动”的瀑布
ON DELETE CASCADE 的作用方向是单向且固定的：它只在“父表被删”时，触发“子表中引用该父记录的行”被自动删除。而决定谁是“父”、谁是“子”的关键，在于外键的定义位置：
- ✅ 正确逻辑：若一个 email 属于某个 account（即 email 依赖 account 存在），则 emails 表应通过外键引用 accounts.id → 此时 accounts 是父表，emails 是子表，ON DELETE CASCADE 才会在删除 account 时级联删除其 emails。
- ❌ 当前错误：你的 AccountsModel 中 email_id: ForeignKey('emails.id', ondelete='CASCADE') 表示 account 依赖 email —— 即 email 是父表，account 是子表。因此，只有当你 DELETE FROM emails WHERE id = ? 时，才会级联删除对应 accounts 记录；而你执行的是 DELETE FROM accounts，SQLite 完全无视该外键的 CASCADE，仅删除 accounts 行。
✅ 正确建模：将外键移至 EmailsModel
根据业务语义（邮件属于账户），应重构模型如下：
class AccountsModel(Base):
__tablename__ = 'accounts'
id: Mapped[intpk]
# 移除 email_id 外键字段（不再由 account 持有 email 主键）
# email 关系保持，但改为 lazy 加载避免循环依赖
emails: Mapped[List["EmailsModel"]] = relationship(
back_populates="account",
cascade="all, delete-orphan", # ORM 层级级联（辅助，非替代 DB 级联）
lazy="selectin"
)
class EmailsModel(Base):
__tablename__ = 'emails'
id: Mapped[intpk]
email: Mapped[str_255] = mapped_column(unique=True)
# ✅ 外键定义在子表 emails 上，引用父表 accounts
account_id: Mapped[int] = mapped_column(ForeignKey('accounts.id', ondelete='CASCADE'))
account: Mapped["AccountsModel"] = relationship(
back_populates="emails",
lazy="joined"
)
? 注意：ondelete='CASCADE' 必须配合 SQLite 的 PRAGMA foreign_keys=ON 生效。你已在 SessionMaker._set_sqlite_pragma 中正确启用，这是必要前提。
? 验证级联是否生效
执行以下测试代码（确保先创建表）：
# 删除 account，观察 emails 是否被自动删除
async def test_cascade():
async with sessionmaker()() as session:
# 创建测试数据
acc = AccountsModel()
session.add(acc)
await session.flush() # 获取 acc.id
email = EmailsModel(email="test@example.com", account_id=acc.id)
session.add(email)
await session.commit()
# 删除 account
await session.execute(delete(AccountsModel).where(AccountsModel.id == acc.id))
await session.commit()
# 查询 emails，应返回空结果
result = await session.execute(select(EmailsModel).where(EmailsModel.account_id == acc.id))
assert result.scalars().all() == [] # ✅ 断言通过，级联生效
⚠️ 关键注意事项
- 不要混淆 ORM cascade 与 DB ON DELETE CASCADE：relationship(cascade='all, delete-orphan') 是 SQLAlchemy ORM 层的删除策略，用于 session.delete(obj) 场景；而 ForeignKey(ondelete='CASCADE') 是数据库约束，对原生 SQL DELETE 语句生效。两者常需配合使用，但作用域不同。
- SQLite 的限制：ON DELETE CASCADE 在 SQLite 中要求外键约束显式启用（你已做到），且仅对 FOREIGN KEY 列所在的表生效（即级联发生在子表）。
- 双向关系命名：back_populates 的两端名称需严格匹配（如 emails ↔ account），否则关系无法正确建立。
- 迁移影响：修改外键位置需重建表（drop_all + create_all），生产环境请使用 Alembic 进行安全迁移。
遵循以上原则重构模型后，DELETE FROM accounts 将真正触发数据库级联删除，彻底解决“外键未删除映射表行”的问题。
