Implement graph-driven cascade delete and restrict on Diagram

[dimitri-yatsenko]

Summary

Replace the error-driven cascade in Table.delete() with graph-driven restriction propagation using Diagram. The Diagram is purely a graph computation and inspection tool — all mutation logic (transactions, SQL execution, prompts) lives in Table.delete() and Table.drop().

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

Architecture

Table.delete() builds a Diagram, calls cascade() to compute the affected subgraph, then executes the delete itself in reverse topological order. Table.drop() follows the same pattern. The Diagram never executes mutations — it computes the cascade graph and provides preview() for inspection.

New Diagram methods (graph computation / inspection only)

• cascade(table_expr) — OR convergence, one-shot, trims to seed + descendants subgraph
• restrict(table_expr) — AND convergence, chainable, preserves full graph (for export/subsetting)
• 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

Table.delete() and Table.drop() changes

• Table.delete() absorbs all execution logic: transaction management, reverse-topo-order SQL execution, IntegrityError handling for unloaded schemas, part integrity post-check, user confirmation
• Table.drop() absorbs drop execution: part integrity pre-check, reverse-topo-order DROP, user confirmation
• New dry_run parameter: delete(dry_run=True) and drop(dry_run=True) return affected row counts via Diagram.preview() without modifying data
• part_integrity parameter: data-driven post-check 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()

Convergence semantics

• Cascade (delete): OR — a row is deleted if ANY ancestor path reaches it
• Restrict (export): AND — a row is included only if ALL ancestor conditions match

Bug fixes

• Index declaration parsing: Allow inline comments on index lines (e.g., index(y, z) # comment)
• SQL generation: Restrictions applied via restrict() → make_condition() rather than direct _restriction assignment, fixing invalid WHERE clauses

Advantages over previous implementation

Scenario	Error-driven (prior)	Graph-driven (new)
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)
Inspectability	Opaque recursive cascade	preview() / dry_run before executing
Reusability	Delete-only	Delete, drop, export, prune

Files changed

File	Change
src/datajoint/diagram.py	cascade(), restrict(), preview(), prune(), _restricted_table() — no delete()/drop()
src/datajoint/table.py	Table.delete() and Table.drop() own all execution logic, dry_run parameter
src/datajoint/declare.py	Fix index declaration regex to allow trailing comments
src/datajoint/user_tables.py	Part.delete() passes part_integrity and dry_run through
src/datajoint/version.py	Bump to 2.2.0dev0
docs/design/thread-safe-mode.md	Removed (captured in datajoint-docs)
tests/integration/test_cascade_delete.py	New dry_run tests for delete and drop
tests/integration/test_erd.py	Prune tests

Test plan

• All existing cascade delete tests pass (MySQL + PostgreSQL)
• New dry_run tests for delete and drop
• All 20 datajoint-docs tutorials pass against PostgreSQL
• Full suite passes
• Pre-commit hooks pass

🤖 Generated with Claude Code