Refs #29260 -- Doc'd Model.save() behavior change in Django 3.0.

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/releases/3.0.txt b/docs/releases/3.0.txt
index 435755f732..f133c58654 100644
--- a/docs/releases/3.0.txt
+++ b/docs/releases/3.0.txt
@@ -372,6 +372,27 @@ Tests
 Backwards incompatible changes in 3.0
 =====================================
 
+``Model.save()`` when providing a default for the primary key
+-------------------------------------------------------------
+
+:meth:`.Model.save` no longer attempts to find a row when saving a new
+``Model`` instance and a default value for the primary key is provided, and
+always performs a single ``INSERT`` query. In older Django versions,
+``Model.save()`` performed either an ``INSERT`` or an ``UPDATE`` based on
+whether or not the row exists.
+
+This makes calling ``Model.save()`` while providing a default primary key value
+equivalent to passing :ref:`force_insert=True <ref-models-force-insert>` to
+model's ``save()``. Attempts to use a new ``Model`` instance to update an
+existing row will result in an ``IntegrityError``.
+
+In order to update an existing model for a specific primary key value, use the
+:meth:`~django.db.models.query.QuerySet.update_or_create` method or
+``QuerySet.filter(pk=…).update(…)`` instead. For example::
+
+    >>> MyModel.objects.update_or_create(pk=existing_pk, defaults={'name': 'new name'})
+    >>> MyModel.objects.filter(pk=existing_pk).update(name='new name')
+
 Database backend API
 --------------------