本文详解 SQLAlchemy 中 ON DELETE CASCADE 失效的根本原因：外键定义位置错误——级联必须定义在被引用的子表（如 emails）上，而非引用方（如 accounts），才能实现“删除主记录时自动清理关联子记录”的预期行为。
本文详解 sqlalchemy 中 `on delete cascade` 失效的根本原因：外键定义位置错误——级联必须定义在被引用的子表（如 `emails`）上，而非引用方（如 `accounts`），才能实现“删除主记录时自动清理关联子记录”的预期行为。
在使用 SQLAlchemy + SQLite（配合 aiosqlite）构建关系型模型时，许多开发者会误以为只要在 ForeignKey 中声明 ondelete='CASCADE'，就能在删除主表记录时自动级联删除所有被引用的关联行。但实际执行 DELETE FROM accounts WHERE id = ? 后，日志仅显示 accounts 行被删除，而 emails 表中的对应记录依然存在——这并非 SQLAlchemy 或 SQLite 的 Bug，而是外键级联方向理解偏差导致的典型配置错误。
? 核心原理：级联是“向下流动”的（Parent → Child）
ON DELETE CASCADE 的作用方向是单向且明确的：它始终从被引用的父表（Parent）流向引用它的子表（Child）。换言之：
- ✅ 正确场景：若 emails 表通过 account_id 外键引用 accounts.id，则在 emails 表中定义 ForeignKey('accounts.id', ondelete='CASCADE') —— 删除 accounts 中某条记录时，所有 account_id 匹配的 emails 行将被自动删除。
- ❌ 当前错误：你在 accounts.email_id 上定义了 ForeignKey('emails.id', ondelete='CASCADE') —— 这意味着“当 emails 行被删时，对应 accounts 行应被删”，但你的业务逻辑恰恰相反（要删 accounts 时清理 emails），因此级联完全不会触发。
? 简记口诀：“谁被谁引用，级联写在‘被引用’的那一方”。即：级联规则必须定义在 子表（含外键列的表）上，指向 父表（被引用主键所在表）。
✅ 正确建模示例（符合业务语义）
假设一个 Account 拥有多个 Email（即 Email 属于 Account），则 emails 是子表，accounts 是父表：
class AccountsModel(Base):
__tablename__ = 'accounts'
id: Mapped[int] = mapped_column(primary_key=True)
# 其他字段...
class EmailsModel(Base):
__tablename__ = 'emails'
id: Mapped[int] = mapped_column(primary_key=True)
email: Mapped[str] = mapped_column(String(255), unique=True)
account_id: Mapped[int] = mapped_column(
ForeignKey('accounts.id', ondelete='CASCADE') # ✅ 级联定义在此！
)
account: Mapped['AccountsModel'] = relationship(
back_populates='emails',
lazy='selectin'
)
# 在 AccountsModel 中反向定义关系（无需外键）
class AccountsModel(Base):
# ...
emails: Mapped[List['EmailsModel']] = relationship(
back_populates='account',
cascade='all, delete-orphan', # ⚠️ 注意：此 cascade 控制 ORM 层级联，不替代数据库级联
passive_deletes=True # ✅ 关键！启用 ORM 对数据库级联的感知（避免 SQLAlchemy 自行 DELETE 子记录）
)⚙️ 必要配置补充
-
SQLite 启用外键约束（你已正确实现）：
@event.listens_for(Engine, 'connect') def _set_sqlite_pragma(conn, record): cursor = conn.cursor() cursor.execute('PRAGMA foreign_keys=ON') cursor.close() ORM 层需配合 passive_deletes=True
若未设置，SQLAlchemy 在删除 Account 时会先主动发出 DELETE FROM emails WHERE account_id = ?，绕过数据库级联，导致行为不可控。启用后，SQLA 信任数据库完成级联，仅执行主表 DELETE。验证 DDL 是否生效
执行 CREATE TABLE emails (...) 时，确保生成的 SQL 包含 FOREIGN KEY(account_id) REFERENCES accounts(id) ON DELETE CASCADE。可通过 Base.metadata.create_all(..., echo=True) 或 sqlite3 CLI 查看表结构确认。
? 验证级联是否生效
# 删除 Account 后，检查 emails 是否自动消失
async with session.begin():
await session.execute(delete(AccountsModel).where(AccountsModel.id == target_id))
# ✅ 此时 emails 表中 account_id = target_id 的行已被 SQLite 自动删除? 总结与最佳实践
- 外键级联是数据库层能力，非 ORM 特性：ondelete='CASCADE' 最终由 SQLite 执行，SQLAlchemy 仅负责生成合规 DDL 和适配查询。
- 关系方向决定外键位置：理清“谁属于谁”——子实体（如 Email）必须在其表中定义外键指向父实体（如 Account）。
- ORM 与 DB 级联协同：cascade='all, delete-orphan' 处理 Python 对象图一致性；passive_deletes=True + ON DELETE CASCADE 处理数据库数据一致性；二者缺一不可。
- 避免冗余逻辑：切勿在应用层手动 session.delete(email) —— 这会干扰级联，且降低性能与可靠性。
遵循以上原则，即可让 DELETE FROM accounts 真正触发瀑布式清理，彻底解决“外键未级联删除”的问题。
