From: Mike Bayer Date: Sat, 7 Jun 2025 13:01:14 +0000 (-0400) Subject: update docs for "copy column" warning X-Git-Tag: rel_2_0_42~43 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0518e7564e3cd8ab7ba426d6b50bc5d83e9b50e3;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git update docs for "copy column" warning these docs failed to mention we're talking about ORM flush References: #12650 Change-Id: I3a1655ba99e98021327c90d5cd0c0f8258f4ddc6 (cherry picked from commit 39142af868c0bd98e6ce59c009e62a597a2452f2) --- diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index 1a26d94a8b..6422a74875 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -424,13 +424,19 @@ What this refers to originates from the fact that ``Article.magazine_id`` is the subject of two different foreign key constraints; it refers to ``Magazine.id`` directly as a source column, but also refers to ``Writer.magazine_id`` as a source column in the context of the -composite key to ``Writer``. If we associate an ``Article`` with a -particular ``Magazine``, but then associate the ``Article`` with a -``Writer`` that's associated with a *different* ``Magazine``, the ORM -will overwrite ``Article.magazine_id`` non-deterministically, silently -changing which magazine to which we refer; it may -also attempt to place NULL into this column if we de-associate a -``Writer`` from an ``Article``. The warning lets us know this is the case. +composite key to ``Writer``. + +When objects are added to an ORM :class:`.Session` using :meth:`.Session.add`, +the ORM :term:`flush` process takes on the task of reconciling object +refereneces that correspond to :func:`_orm.relationship` configurations and +delivering this state to the databse using INSERT/UPDATE/DELETE statements. In +this specific example, if we associate an ``Article`` with a particular +``Magazine``, but then associate the ``Article`` with a ``Writer`` that's +associated with a *different* ``Magazine``, this flush process will overwrite +``Article.magazine_id`` non-deterministically, silently changing which magazine +to which we refer; it may also attempt to place NULL into this column if we +de-associate a ``Writer`` from an ``Article``. The warning lets us know that +this scenario may occur during ORM flush sequences. To solve this, we need to break out the behavior of ``Article`` to include all three of the following features: