Docs for "Automatic primary key fields" should mention surprising behavior

[Eric Hanchrow]

I spent a fair bit of time investigating an IntegrityError in my code, and eventually discovered that automatic primary key fields don't work *quite* as I expected. This is not a bug, but is surprising, and thus ought to be pointed out somewhere in the docs.

Here are the details.

I have a model which uses the default automatic primary key:

class Thing(models.Model):
    def __str__(self):
        return f"Thing #{self.pk}"

I have some code which creates instances two different ways: both with, and without, specifying a primary key:

class TheOneTestCase(TestCase):
    def test_whatever(self):
        Thing.objects.create(pk=2)

        Thing.objects.create()
        Thing.objects.create()

        self.assertEqual(Thing.objects.count(), 3)

When I run this code with sqlite as the database, it passes, and creates instances with primary key values of 2, 3, and 4.

However, when I run this code with postgresql as the database, the third (i.e., the last) "create" call raises an exception:

django.db.utils.IntegrityError: duplicate key value violates unique constraint "app_thing_pkey"

As best I can tell, this is not a bug; it's simply how Postgresql's sequences behave.

Anyway, since it surprised me, it might surprise other developers too, and thus ought to be mentioned somewhere in the docs.

[Adam Zapletal]

Eric, does this part of the PostgreSQL docs already cover it?

​https://docs.djangoproject.com/en/5.1/ref/databases/#manually-specifying-values-of-auto-incrementing-primary-keys

[Mariusz Felisiak]

Like Adam said, it's already documented.

[Eric Hanchrow]

Replying to Adam Zapletal:

Eric, does this part of the PostgreSQL docs already cover it?

​https://docs.djangoproject.com/en/5.1/ref/databases/#manually-specifying-values-of-auto-incrementing-primary-keys

Yes, that describes it exactly :-(. Somehow I failed to notice that section when I was debugging.

Perhaps we can include a link to that section from ​the topic?

[Eric Hanchrow]

I suggest a link like this​https://github.com/offby1/django/blob/c44c784c8eb4df47c183f953c13461d30ad245ae/docs/topics/db/models.txt#L297.

[Eric Hanchrow]

It does not suffice to say "this is already documented". My point is that, despite reasonable effort, I did not encounter the existing documentation, and therefore, the docs as a whole could be improved by a link to the existing documentation, from the section that I *did* encounter.

[Tim Graham]

Eric, I sympathize with your frustration. Unfortunately, we cannot add links to all possible problems from all possible locations. For example, third-party database backends do not get this sort of special treatment.