Document effects of saving a model after changing its primary key

[Vedant Lath]

When the value of a primary key field in a record is changed in the admin interface, a new record gets created and the previous record is untouched. This means that the primary key field of a model is effectively read-only and its values cannot be changed.

Steps to reproduce:

1. Define a model M as:

   class M(models.Model):
       name = models.CharField(max_length=200, primary_key=True)
   

2. Create a record in M with name as 'ABC' and save it.
3. Change the name in the above record to 'XYZ' and save it.

Expected result:
the record 'ABC' is changed to 'XYZ' with an SQL UPDATE command.

Actual result:
a new record 'XYZ' is created and the previous record 'ABC' also exists. No warning or any other message is shown.

If this is intended behaviour, it should be documented appropriately in the primary_key parameter and maybe other places.

[Tim Graham]

Documentation seems like the way to go as changing the behavior would not only be backward incompatible, but could also require updating ForeignKey constraints.

[Helen Sherwood-Taylor]

PR: ​https://github.com/django/django/pull/3787

I added docs into both the refs and topics areas. This is a lot of duplication but that is already quite true of those two files. I'm not sure whether this info belongs more in one or the other... or just both.

[Tim Graham <timograham@…>]

In 4ccdf6e57f49d7e981dcd88c1db65229b8b92487:

Fixed #24041 -- Documented effect of changing a model instance's primary key.

[Tim Graham <timograham@…>]

In 2d0ae995d6b2fb58853fc59802ad781ba03376a6:

[1.6.x] Fixed #24041 -- Documented effect of changing a model instance's primary key.

Backport of 4ccdf6e57f49d7e981dcd88c1db65229b8b92487 from master

[Tim Graham <timograham@…>]

In b9169a100d4a836e3401395dc1e5bf120a36887d:

[1.7.x] Fixed #24041 -- Documented effect of changing a model instance's primary key.

Backport of 4ccdf6e57f49d7e981dcd88c1db65229b8b92487 from master