diff options
| author | François Freitag <mail@franek.fr> | 2017-05-27 18:12:18 -0700 |
|---|---|---|
| committer | Tim Graham <timograham@gmail.com> | 2017-06-01 15:38:30 -0400 |
| commit | bf50ae821021c4f7cd608d2bd1f2dfff98f3ceb9 (patch) | |
| tree | 9503fde717aad556235f9b63eb2531e7e063582b /docs/ref | |
| parent | 9af6c97504ef2b06dd5292d03ea94d3eb5d8c4d6 (diff) | |
Clarified QuerySet.iterator()'s docs on server-side cursors.
Diffstat (limited to 'docs/ref')
| -rw-r--r-- | docs/ref/models/querysets.txt | 27 |
1 files changed, 22 insertions, 5 deletions
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 |