Clarified QuerySet.iterator()'s docs on server-side cursors.

2 files changed, 24 insertions, 6 deletions

diff --git a/docs/_theme/djangodocs/static/djangodocs.css b/docs/_theme/djangodocs/static/djangodocs.css
index 22fce2a158..143bcdb6c9 100644
--- a/docs/_theme/djangodocs/static/djangodocs.css
+++ b/docs/_theme/djangodocs/static/djangodocs.css
@@ -43,11 +43,12 @@ div.nav { margin: 0; font-size: 11px; text-align: right; color: #487858;}
 
 /*** basic styles ***/
 dd { margin-left:15px; }
-h1,h2,h3,h4 { margin-top:1em; font-family:"Trebuchet MS",sans-serif; font-weight:normal; }
+h1,h2,h3,h4,h5 { margin-top:1em; font-family:"Trebuchet MS",sans-serif; font-weight:normal; }
 h1 { font-size:218%; margin-top:0.6em; margin-bottom:.4em; line-height:1.1em; }
 h2 { font-size:175%; margin-bottom:.6em; line-height:1.2em; color:#092e20; }
 h3 { font-size:150%; font-weight:bold; margin-bottom:.2em; color:#487858; }
 h4 { font-size:125%; font-weight:bold; margin-top:1.5em; margin-bottom:3px; }
+h5 { font-size:110%; font-weight:bold; margin-top:1em; margin-bottom:3px; }
 div.figure { text-align: center; }
 div.figure p.caption { font-size:1em; margin-top:0; margin-bottom:1.5em; color: #555;}
 hr { color:#ccc; background-color:#ccc; height:1px; border:0; }
diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt
index 38c6d84b0b..cc80069894 100644
--- a/docs/ref/models/querysets.txt
+++ b/docs/ref/models/querysets.txt
@@ -2021,15 +2021,32 @@ evaluated will force it to evaluate again, repeating the query.
 Also, use of ``iterator()`` causes previous ``prefetch_related()`` calls to be
 ignored since these two optimizations do not make sense together.
 
-Some Python database drivers still load the entire result set into memory, but
-won't cache results after iterating over them. Oracle and :ref:`PostgreSQL
-<postgresql-server-side-cursors>` use server-side cursors to stream results
-from the database without loading the entire result set into memory.
+Depending on the database backend, query results will either be loaded all at
+once or streamed from the database using server-side cursors.
+
+With server-side cursors
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Oracle and :ref:`PostgreSQL <postgresql-server-side-cursors>` use server-side
+cursors to stream results from the database without loading the entire result
+set into memory.
+
+The Oracle database driver always uses server-side cursors.
 
 On PostgreSQL, server-side cursors will only be used when the
 :setting:`DISABLE_SERVER_SIDE_CURSORS <DATABASE-DISABLE_SERVER_SIDE_CURSORS>`
 setting is ``False``. Read :ref:`transaction-pooling-server-side-cursors` if
-you're using a connection pooler configured in transaction pooling mode.
+you're using a connection pooler configured in transaction pooling mode. When
+server-side cursors are disabled, the behavior is the same as databases that
+don't support server-side cursors.
+
+Without server-side cursors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+MySQL and SQLite don't support streaming results, hence the Python database
+drivers load the entire result set into memory. The result set is then
+transformed into Python row objects by the database adapter using the
+``fetchmany()`` method defined in :pep:`249`.
 
 .. versionchanged:: 1.11