From bf50ae821021c4f7cd608d2bd1f2dfff98f3ceb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= Date: Sat, 27 May 2017 18:12:18 -0700 Subject: [PATCH] Clarified QuerySet.iterator()'s docs on server-side cursors. --- docs/_theme/djangodocs/static/djangodocs.css | 3 ++- docs/ref/models/querysets.txt | 27 ++++++++++++++++---- 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 -` 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 ` 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 ` 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