[3.1.x] Refs #28939 -- Doc’d Prefetch behavior with multiple DBs.

Backport of 8c0794ba0da2b5d668a7eb1c167e54beb7f40890 from master

1 files changed, 24 insertions, 0 deletions

diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 1b3f703bdf..ff750dd457 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -1245,6 +1245,26 @@ where prefetching with a custom ``QuerySet`` is useful:
     >>> restaurants = Restaurant.objects.prefetch_related(
     ...     Prefetch('best_pizza', queryset=queryset))
 
+When using multiple databases, ``Prefetch`` will respect your choice of
+database. If the inner query does not specify a database, it will use the
+database selected by the outer query. All of the following are valid::
+
+    >>> # Both inner and outer queries will use the 'replica' database
+    >>> Restaurant.objects.prefetch_related('pizzas__toppings').using('replica')
+    >>> Restaurant.objects.prefetch_related(
+    ...     Prefetch('pizzas__toppings'),
+    ... ).using('replica')
+    >>>
+    >>> # Inner will use the 'replica' database; outer will use 'default' database
+    >>> Restaurant.objects.prefetch_related(
+    ...     Prefetch('pizzas__toppings', queryset=Toppings.objects.using('replica')),
+    ... )
+    >>>
+    >>> # Inner will use 'replica' database; outer will use 'cold-storage' database
+    >>> Restaurant.objects.prefetch_related(
+    ...     Prefetch('pizzas__toppings', queryset=Toppings.objects.using('replica')),
+    ... ).using('cold-storage')
+
 .. note::
 
     The ordering of lookups matters.
@@ -3655,6 +3675,10 @@ lookups or :class:`Prefetch` objects you want to prefetch for. For example::
     >>> restaurants = fetch_top_restaurants_from_cache()  # A list of Restaurants
     >>> prefetch_related_objects(restaurants, 'pizzas__toppings')
 
+When using multiple databases with ``prefetch_related_objects``, the prefetch
+query will use the database associated with the model instance. This can be
+overridden by using a custom queryset in a related lookup.
+
 ``FilteredRelation()`` objects
 ------------------------------