= !BluePrint: Deletion Cascades =
[[TOC]]

== Introduction ==

Deleting a record in Sahana Eden may require to update (or even delete) other records in other tables as well, in order to ensure the referential integrity of the database.

Currently, this is controlled by the ondelete-setting of foreign key constraints:

  ||'''ondelete'''||'''Behavior'''||
  ||RESTRICT||prevents the deletion of the referenced record as long as there is still at least one reference||
  ||CASCADE||deletes the referencing record as well||
  ||SET DEFAULT||changes the foreign key in the referencing record to its default value||
  ||SET NULL||changes the foreign key in the referencing record to NULL||

Additionally, it is possible to define a custom ondelete-cascade for a table.

== Description ==

The proposed change will allow a controlled override of the RESTRICT setting in 3 stages:

  - conditional restrict-override: automatically override a RESTRICT under certain conditions and perform predefined cascading methods
  - user confirmed restrict-override: requests user confirmation to override a RESTRICT (and perform pre-defined cascading methods)
  - user-defined conditional cascades: requests cascading methods from the user to override a RESTRICT

== Requirements ==

The implementation of this BluePrint requires:

  - an "undelete" REST method to undelete records (and their original refences)
  - a framework to reconstruct for deleted records (both, for undelete and represent)
  - a conditional two-phase "delete" REST method which can present forms to the user
  - a cascading method "SKIP" which "soft-deletes" (archives) the referenced record but retains the reference
  - a user confirmation dialog when auto-deleting linktable-linked components

== Use-Cases ==

  - ''tbw''

== Design ==

=== Conditional RESTRICT Override ===

This should implement a hook which can be called whenever resource.delete() finds a RESTRICT, and which returns an alternative action which can then be used to run through the normal cascade (where it turns RESTRICT again, the cascade would stop).

=== User-confirmed RESTRICT Override ===

This should implement a user dialog:

  - GET delete would return a list of records which have a RESTRICT for the current record
  - each item in the list explains the cascade action
  - the user can confirm the whole cascade or abort the attempt

=== User-defined Action upon RESTRICT Override ===

  - GET delete would return a list of records which have a RESTRICT for the current record
  - each item in the list has a selector of possible cascade actions
  - the user can alter the cascade actions, confirm the whole cascade or abort the attempt

== Implementation ==

  - not started yet

== References ==

----
BluePrints