Added the ability to force an SQL insert (or force an update) via a model's

save() method.


git-svn-id: http://code.djangoproject.com/svn/django/trunk@8267 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 20 insertions, 2 deletions

diff --git a/docs/db-api.txt b/docs/db-api.txt
index 7e6406f334..bbbe06ea98 100644
--- a/docs/db-api.txt
+++ b/docs/db-api.txt
@@ -213,8 +213,26 @@ follows this algorithm:
 
 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.
+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.
+
+Forcing an INSERT or UPDATE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**New in Django development version**
+
+In some rare circumstances, it's necesary to be able to force the ``save()``
+method to perform an SQL ``INSERT`` and not fall back to doing an ``UPDATE``.
+Or vice-versa: update, if possible, but not insert a new row. In these cases
+you can pass the ``force_insert=True`` or ``force_update=True`` parameters to
+the ``save()`` method. Passing both parameters is an error, since you cannot
+both insert *and* update at the same time.
+
+It should be very rare that you'll need to use these parameters. Django will
+almost always do the right thing and trying to override that will lead to
+errors that are difficult to track down. This feature is for advanced use
+only.
 
 Retrieving objects
 ==================