Make database selection for subqueries consistent and document its behavior

[Lev Zlobin]

• Without an explicitly selected database, the subquery uses the outer query's connection rather than being routed independently.
• Explicitly selecting a different database for the inner queryset raises ValueError.
• Evaluating the inner queryset with list() allows values to be retrieved from another database.

Add examples to the multiple-databases guide and cross-references from the using() and in lookup documentation.

This documentation improvement was split out from https://code.djangoproject.com/ticket/37427 following review on github ​https://github.com/django/django/pull/22154.

[Sarah Boyce]

From what I can see, the outer query’s database connection is also used for Subquery() and Exists() but unlike the in lookup, these silently ignore an explicit database selection on the inner queryset. See below:

tests/multiple_database/tests.py

@@ -8 +8 @@
 from django.contrib.contenttypes.models import ContentType
 from django.core import management
 from django.db import DEFAULT_DB_ALIAS, router, transaction
-from django.db.models import signals
+from django.db.models import Exists, Subquery, signals
 from django.db.utils import ConnectionRouter
 from django.test import SimpleTestCase, TestCase, override_settings, skipIfDBFeature
 
@@ -1963 +1963 @@
         # If you evaluate the query, it should work, running on 'other'
         self.assertEqual(list(qs.values_list("title", flat=True)), ["Dive into Python"])
 
+    def test_subquery_explicit_database_selection(self):
+        Person.objects.using("default").create(name="Default person")
+        Person.objects.using("other").create(name="Other person")
+        book = Book.objects.using("other").create(
+            title="Test book",
+            published=datetime.date(2026, 1, 1),
+        )
+
+        inner = Person.objects.using("default").order_by("name")
+        outer = Book.objects.using("other").filter(pk=book.pk)
+
+        # Should Subquery() and Exists() raise ValueError for conflicting
+        # database selections, as the __in lookup does?
+        with self.assertNumQueries(0, using="default"):
+            with self.assertNumQueries(1, using="other"):
+                result = outer.annotate(
+                    person_name=Subquery(inner.values("name")[:1]),
+                    has_default_person=Exists(inner.filter(name="Default person")),
+                ).get()
+
+        self.assertEqual(result.person_name, "Other person")
+        self.assertIs(result.has_default_person, False)
+
+        with self.assertRaisesMessage(
+            ValueError,
+            "Subqueries aren't allowed across different databases.",
+        ):
+            list(outer.filter(title__in=inner.values("name")))
+
     def test_deferred_models(self):

Perhaps we should document the general database-selection rule in the multiple-databases guide, with cross-references from in, Subquery(), and Exists().
It might also be worth considering whether conflicting explicit database selections should consistently raise an error like what was introduced in #25811