Skip to content

Commit

Permalink
Clarified QuerySet.iterator()'s docs on server-side cursors.
Browse files Browse the repository at this point in the history
  • Loading branch information
francoisfreitag authored and timgraham committed Jun 1, 2017
1 parent 9af6c97 commit bf50ae8
Show file tree
Hide file tree
Showing 2 changed files with 24 additions and 6 deletions.
3 changes: 2 additions & 1 deletion docs/_theme/djangodocs/static/djangodocs.css
Original file line number Diff line number Diff line change
Expand Up @@ -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; }
Expand Down
27 changes: 22 additions & 5 deletions docs/ref/models/querysets.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit bf50ae8

Please sign in to comment.