From e973ee6a9879969b8ae05bb7ff681172cc5386a5 Mon Sep 17 00:00:00 2001 From: Anssi Kääriäinen Date: Fri, 30 Aug 2013 09:41:07 +0300 Subject: Fixed #20988 -- Added model meta option select_on_save The option can be used to force pre 1.6 style SELECT on save behaviour. This is needed in case the database returns zero updated rows even if there is a matching row in the DB. One such case is PostgreSQL update trigger that returns NULL. Reviewed by Tim Graham. Refs #16649 --- docs/ref/models/instances.txt | 17 ++++++++++++----- docs/ref/models/options.txt | 22 ++++++++++++++++++++++ 2 files changed, 34 insertions(+), 5 deletions(-) (limited to 'docs/ref') diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index da657a9a01..d195936964 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -305,16 +305,23 @@ follows this algorithm: * If the object's primary key attribute is *not* set or if the ``UPDATE`` didn't update anything, Django executes an ``INSERT``. -.. versionchanged:: 1.6 - - Previously Django used ``SELECT`` - if not found ``INSERT`` else ``UPDATE`` - algorithm. The old algorithm resulted in one more query in ``UPDATE`` case. - The one gotcha here is that you should be careful not to specify a primary-key value explicitly when saving new objects, if you cannot guarantee the primary-key value is unused. For more on this nuance, see `Explicitly specifying auto-primary-key values`_ above and `Forcing an INSERT or UPDATE`_ below. +.. versionchanged:: 1.6 + + Previously Django did a ``SELECT`` when the primary key attribute was set. + If the ``SELECT`` found a row, then Django did an ``UPDATE``, otherwise it + did an ``INSERT``. The old algorithm results in one more query in the + ``UPDATE`` case. There are some rare cases where the database doesn't + report that a row was updated even if the database contains a row for the + object's primary key value. An example is the PostgreSQL ``ON UPDATE`` + trigger which returns ``NULL``. In such cases it is possible to revert to the + old algorithm by setting the :attr:`~django.db.models.Options.select_on_save` + option to ``True``. + .. _ref-models-force-insert: Forcing an INSERT or UPDATE diff --git a/docs/ref/models/options.txt b/docs/ref/models/options.txt index baa24f63cb..7f5d193a89 100644 --- a/docs/ref/models/options.txt +++ b/docs/ref/models/options.txt @@ -256,6 +256,28 @@ Django quotes column and table names behind the scenes. If ``proxy = True``, a model which subclasses another model will be treated as a :ref:`proxy model `. +``select_on_save`` +------------------ + +.. attribute:: Options.select_on_save + + .. versionadded:: 1.6 + + Determines if Django will use the pre-1.6 + :meth:`django.db.models.Model.save()` algorithm. The old algorithm + uses ``SELECT`` to determine if there is an existing row to be updated. + The new algorith tries an ``UPDATE`` directly. In some rare cases the + ``UPDATE`` of an existing row isn't visible to Django. An example is the + PostgreSQL ``ON UPDATE`` trigger which returns ``NULL``. In such cases the + new algorithm will end up doing an ``INSERT`` even when a row exists in + the database. + + Usually there is no need to set this attribute. The default is + ``False``. + + See :meth:`django.db.models.Model.save()` for more about the old and + new saving algorithm. + ``unique_together`` ------------------- -- cgit v1.3