Cascatas no SQLAlchemy: delete-orphan e ON DELETE resolve um problema recorrente em projetos Python: Expresse quem é dono do ciclo de vida de objetos relacionados e quem executa a exclusão. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
Cascata ORM propaga operações da Session; ON DELETE pertence à foreign key no banco. Elas são camadas diferentes que precisam concordar.
Para revisar os fundamentos relacionados, consulte também o guia de relacionamentos SQLAlchemy. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
class Order(Base):
items: Mapped[list["Item"]] = relationship(
back_populates="order",
cascade="all, delete-orphan",
passive_deletes=True,
)
class Item(Base):
order_id: Mapped[int] = mapped_column(
ForeignKey("orders.id", ondelete="CASCADE")
)Use delete-orphan apenas quando o filho não faz sentido sem um único pai. passive_deletes permite confiar no banco para coleções não carregadas.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Aplicar delete nos dois lados de muitos-para-muitos pode percorrer e apagar um grafo inteiro. Bulk delete não executa cascatas ORM por instância.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste remover o pai, desassociar um filho e executar exclusão em massa, sempre conferindo as linhas que permanecem.