Implement graph-driven cascade delete and restrict on Diagram

[dimitri-yatsenko]

Summary

Replace the error-driven cascade in Table.delete() (~200 lines) with graph-driven restriction propagation on Diagram. Table.delete() and Table.drop() now delegate to Diagram.cascade().delete() and Diagram.drop() respectively.

Resolves: #865 (applying restrictions to a Diagram), #1110 (cascade delete fails on MySQL 8 with limited privileges)

New Diagram methods

• cascade(table_expr) — OR at convergence, one-shot, for delete
• restrict(table_expr) — AND at convergence, chainable, for export
• delete() — execute cascade delete in reverse topo order
• drop() — drop tables in reverse topo order
• preview() — show affected tables and row counts without modifying data
• prune() — remove tables with zero matching rows from the diagram
• _from_table() — lightweight internal factory for Table.delete/Table.drop

Architecture changes

• Single Diagram class: Removed the if diagram_active: conditional. Diagram(nx.DiGraph) is always defined. Only visualization methods (draw, make_dot, make_svg, etc.) are gated on diagram_active.
• Table.delete() rewritten: ~200 lines → ~10 lines delegating to Diagram
• Table.drop() rewritten: ~35 lines → ~10 lines delegating to Diagram
• dry_run support: delete(dry_run=True) and drop(dry_run=True) return affected row counts without modifying data
• part_integrity: Data-driven post-check — only raises when rows were actually deleted from a Part without its master also being deleted. Avoids false positives when a Part table appears in the cascade graph but has zero affected rows.

Restriction propagation rules

For edge Parent→Child with attr_map:

Condition	Child restriction
Non-aliased AND parent_attrs ⊆ child.primary_key	Copy parent restriction directly
Aliased FK (fk_attrs ≠ pk_attrs)	parent.proj(**{fk: pk for fk, pk in attr_map.items()})
Non-aliased AND parent_attrs ⊄ child.primary_key	parent.proj()

SQL generation fix

Restrictions are applied via restrict() → make_condition() rather than direct assignment to _restriction. This ensures AndList and QueryExpression objects are properly converted to SQL, fixing invalid WHERE clauses that caused 30+ test failures.

Convergence semantics

• Cascade (delete): OR convergence — a row is deleted if ANY of its FK references point to a deleted row. Implemented by passing the restriction list to restrict() which creates an OrList.
• Restrict (export): AND convergence — a row is included only if ALL ancestor conditions are satisfied. Implemented by iterating restrictions and calling restrict() for each.

Advantages over previous implementation

	Previous (error-driven)	New (graph-driven)
MySQL 8 + limited privileges	Crashes (#1110)	Works — no error parsing needed
PostgreSQL	Savepoint overhead per attempt	No errors triggered
part_integrity	Post-hoc check after delete	Data-driven post-check (no false positives on empty tables)
Reusability	Delete-only	Delete, drop, export, backup
Inspectability	Opaque recursive cascade	preview() / dry_run shows affected data before executing

Files changed

File	Change
src/datajoint/diagram.py	_restrict_freetable() helper, cascade(), restrict(), delete(), drop(), preview(), prune() with proper SQL generation and OR/AND convergence
src/datajoint/table.py	Table.delete() and Table.drop() delegate to Diagram, dry_run parameter added
src/datajoint/user_tables.py	Part.drop() passes part_integrity and dry_run through
tests/integration/test_cascade_delete.py	New dry_run tests for delete and drop
tests/integration/test_cascading_delete.py	Fixture cleanup
tests/integration/test_cli.py	Fix subprocess to use sys.executable -m datajoint.cli

Test plan

• All 12 existing test_cascading_delete.py tests pass
• All 10 test_cascade_delete.py tests pass (5 MySQL + 5 PostgreSQL, including dry_run)
• All 12 test_erd.py tests pass (including 5 prune tests)
• All 5 test_cli.py tests pass
• Full suite: 792 passed, 10 skipped, 0 errors

See docs/design/restricted-diagram-spec.md for the full implementation spec.

🤖 Generated with Claude Code