diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 5eabf84cad..35997801fb 100644 --- a/docs/ref/models/fields.txt +++ b/docs/ref/models/fields.txt @@ -278,8 +278,13 @@ don't need to set ``primary_key=True`` on any of your fields unless you want to override the default primary-key behavior. For more, see :ref:`automatic-primary-key-fields`. -``primary_key=True`` implies :attr:`null=False ` and :attr:`unique=True `. -Only one primary key is allowed on an object. +``primary_key=True`` implies :attr:`null=False ` and +:attr:`unique=True `. Only one primary key is allowed on an +object. + +The primary key field is read-only. If you change the value of the primary +key on an existing object and then save it, a new object will be created +alongside the old one. ``unique`` ---------- diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt index a134a94073..754cdce13d 100644 --- a/docs/topics/db/models.txt +++ b/docs/topics/db/models.txt @@ -213,6 +213,23 @@ ones: unless you want to override the default primary-key behavior. For more, see :ref:`automatic-primary-key-fields`. + The primary key field is read-only. If you change the value of the primary + key on an existing object and then save it, a new object will be created + alongside the old one. For example:: + + from django.db import models + + class Fruit(models.Model): + name = models.CharField(max_length=100, primary_key=True) + + .. code-block:: pycon + + >>> fruit = Fruit.objects.create(name='Apple') + >>> fruit.name = 'Pear' + >>> fruit.save() + >>> Fruit.objects.values_list('name', flat=True) + ['Apple', 'Pear'] + :attr:`~Field.unique` If ``True``, this field must be unique throughout the table.