diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ref/databases.txt | 18 | ||||
| -rw-r--r-- | docs/ref/models/querysets.txt | 14 | ||||
| -rw-r--r-- | docs/releases/1.11.txt | 9 |
3 files changed, 34 insertions, 7 deletions
diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 51feceea04..16addc52bc 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -171,6 +171,24 @@ If you need to add a PostgreSQL extension (like ``hstore``, ``postgis``, etc.) using a migration, use the :class:`~django.contrib.postgres.operations.CreateExtension` operation. +.. _postgresql-server-side-cursors: + +Server-side cursors +------------------- + +.. versionadded:: 1.11 + +When using :meth:`QuerySet.iterator() +<django.db.models.query.QuerySet.iterator>`, Django opens a :ref:`server-side +cursor <psycopg2:server-side-cursors>`. By default, PostgreSQL assumes that +only the first 10% of the results of cursor queries will be fetched. The query +planner spends less time planning the query and starts returning results +faster, but this could diminish performance if more than 10% of the results are +retrieved. PostgreSQL's assumptions on the number of rows retrieved for a +cursor query is controlled with the `cursor_tuple_fraction`_ option. + +.. _cursor_tuple_fraction: https://www.postgresql.org/docs/current/static/runtime-config-query.html#GUC-CURSOR-TUPLE-FRACTION + Test database templates ----------------------- diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 3090251659..5fe783514d 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1981,15 +1981,15 @@ 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. -.. warning:: +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. + +.. versionchanged:: 1.11 - Some Python database drivers like ``psycopg2`` perform caching if using - client side cursors (instantiated with ``connection.cursor()`` and what - Django's ORM uses). Using ``iterator()`` does not affect caching at the - database driver level. To disable this caching, look at `server side - cursors`_. + PostgreSQL support for server-side cursors was added. -.. _server side cursors: http://initd.org/psycopg/docs/usage.html#server-side-cursors ``latest()`` ~~~~~~~~~~~~ diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt index 9be1f4c53d..9bb9a2e903 100644 --- a/docs/releases/1.11.txt +++ b/docs/releases/1.11.txt @@ -273,6 +273,11 @@ Database backends * Added the :setting:`TEST['TEMPLATE'] <TEST_TEMPLATE>` setting to let PostgreSQL users specify a template for creating the test database. +* :meth:`.QuerySet.iterator()` now uses :ref:`server-side cursors + <psycopg2:server-side-cursors>` on PostgreSQL. This feature transfers some of + the worker memory load (used to hold query results) to the database and might + increase database memory usage. + Email ~~~~~ @@ -527,6 +532,10 @@ Database backend API * Renamed the ``ignores_quoted_identifier_case`` feature to ``ignores_table_name_case`` to more accurately reflect how it is used. +* The ``name`` keyword argument is added to the + ``DatabaseWrapper.create_cursor(self, name=None)`` method to allow usage of + server-side cursors on backends that support it. + Dropped support for PostgreSQL 9.2 and PostGIS 2.0 -------------------------------------------------- |