[3.0.x] Fixed #31502 -- Documented Model._state.db and Model._state.adding

Backport of 697e59d5cf81e6c7e4a06ca98d6e3e16cea486dc from master

1 files changed, 19 insertions, 1 deletions

diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index aef2e0e1dd..b2f5aaa4a8 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -81,7 +81,7 @@ fields are present, then ``values`` are guaranteed to be in the order
 to each of the missing fields.
 
 In addition to creating the new model, the ``from_db()`` method must set the
-``adding`` and ``db`` flags in the new instance's ``_state`` attribute.
+``adding`` and ``db`` flags in the new instance's :attr:`~Model._state` attribute.
 
 Below is an example showing how to record the initial values of fields that
 are loaded from the database::
@@ -854,3 +854,21 @@ Other attributes
     class to identify the class of object that could not be found and to allow
     you to catch a particular model class with ``try/except``. The exception is
     a subclass of :exc:`django.core.exceptions.ObjectDoesNotExist`.
+
+``_state``
+----------
+
+.. attribute:: Model._state
+
+    The ``_state`` attribute refers to a ``ModelState`` object that tracks
+    the lifecycle of the model instance.
+
+    The ``ModelState`` object has two attributes: ``adding``, a flag which is
+    ``True`` if the model has not been saved to the database yet, and ``db``,
+    a string referring to the database alias the instance was loaded from or
+    saved to.
+
+    Newly instantiated instances have ``adding=True`` and ``db=None``,
+    since they are yet to be saved. Instances fetched from a ``QuerySet``
+    will have ``adding=False`` and ``db`` set to the alias of the associated
+    database.