[5.1.x] Fixed #36213 -- Doc'd MySQL's handling of self-select updates in QuerySet.update().

Co-authored-by: Andro Ranogajec <ranogaet@gmail.com>

Backport of be1b776ad8d6f9bccfbdf63f84b16fb81a13119e from main.

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 71af4c5882..0ac8964e40 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2977,6 +2977,14 @@ Using ``update()`` also prevents a race condition wherein something might
 change in your database in the short period of time between loading the object
 and calling ``save()``.
 
+.. admonition:: MySQL does not support self-select updates
+
+    On MySQL, ``QuerySet.update()`` may execute a ``SELECT`` followed by an
+    ``UPDATE`` instead of a single ``UPDATE`` when filtering on related tables,
+    which can introduce a race condition if concurrent changes occur between
+    the queries. To ensure atomicity, consider using transactions or avoiding
+    such filter conditions on MySQL.
+
 Finally, realize that ``update()`` does an update at the SQL level and, thus,
 does not call any ``save()`` methods on your models, nor does it emit the
 :attr:`~django.db.models.signals.pre_save` or