Add restrict_with_error to docs

This commit adds a note to our dev documentation to recommend
using dependent: :restrict_with_error to make sure child objects
are cleaned up before calling .destroy on the parent object.

doc/development/database/loose_foreign_keys.md

@@ -234,6 +234,12 @@ We considered using these Rails features as an alternative to foreign keys but t
 1. These can lead to severe performance degradation as we load all records from PostgreSQL, loop over them in Ruby, and call individual `DELETE` queries.
 1. These can miss data as they only cover the case when the `destroy` method is called directly on the model. There are other cases including `delete_all` and cascading deletes from another parent table that could mean these are missed.
 
+For non-trivial objects that need to clean up data outside the
+database (for example, object storage) where you might wish to use `dependent: :destroy`,
+see alternatives in
+[Avoid `dependent: :nullify` and `dependent: :destroy` across
+databases](./multiple_databases.md#avoid-dependent-nullify-and-dependent-destroy-across-databases).
+
 ## Risks of loose foreign keys and possible mitigations
 
 In general, the loose foreign keys architecture is eventually consistent and

doc/development/database/multiple_databases.md

@@ -623,10 +623,14 @@ outcomes when we switch to decomposed, because now you have some queries
 happening outside the transaction and they may be partially applied while the
 outer transaction fails, which could lead to surprising bugs.
 
-If you need to do some cleanup after a `destroy` you will need to choose
-from some of the options above. If all you need to do is cleanup the child
-records themselves from PostgreSQL then you could consider using ["loose foreign
-keys"](loose_foreign_keys.md).
+For non-trivial objects that need to clean up data outside the
+database (for example, object storage), we recommend the setting
+[`dependent: :restrict_with_error`](https://guides.rubyonrails.org/association_basics.html#options-for-has-one-dependent).
+Such objects should be removed explicitly ahead of time. Using `dependent: :restrict_with_error`
+ensures that we forbid destroying the parent object if something is not cleaned up.
+
+If all you need to do is clean up the child records themselves from PostgreSQL,
+consider using [loose foreign keys](loose_foreign_keys.md).
 
 ## `config/database.yml`
 

doc/development/foreign_keys.md

@@ -80,6 +80,12 @@ foreign keys to remove the data as this would result in the file system data
 being left behind. In such a case you should use a service class instead that
 takes care of removing non database data.
 
+In cases where the relation spans multiple databases you will have even
+further problems using `dependent: :destroy` or the above hooks. You can
+read more about alternatives at [Avoid `dependent: :nullify` and
+`dependent: :destroy` across
+databases](database/multiple_databases.md#avoid-dependent-nullify-and-dependent-destroy-across-databases).
+
 ## Alternative primary keys with has_one associations
 
 Sometimes a `has_one` association is used to create a one-to-one relationship: