diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index 7df2a8e1f9..45b1772514 100644 --- a/docs/ref/databases.txt +++ b/docs/ref/databases.txt @@ -224,6 +224,33 @@ live for the duration of the transaction. .. _pgBouncer: https://pgbouncer.github.io/ +.. _manually-specified-autoincrement-pk: + +Manually-specifying values of auto-incrementing primary keys +------------------------------------------------------------ + +Django uses PostgreSQL's `SERIAL data type`_ to store auto-incrementing primary +keys. A ``SERIAL`` column is populated with values from a `sequence`_ that +keeps track of the next available value. Manually assigning a value to an +auto-incrementing field doesn't update the field's sequence, which might later +cause a conflict. For example:: + + >>> from django.contrib.auth.models import User + >>> User.objects.create(username='alice', pk=1) + + >>> # The sequence hasn't been updated; its next value is 1. + >>> User.objects.create(username='bob') + ... + IntegrityError: duplicate key value violates unique constraint + "auth_user_pkey" DETAIL: Key (id)=(1) already exists. + +If you need to specify such values, reset the sequence afterwards to avoid +reusing a value that's already in the table. The :djadmin:`sqlsequencereset` +management command generates the SQL statements to do that. + +.. _SERIAL data type: https://www.postgresql.org/docs/current/static/datatype-numeric.html#DATATYPE-SERIAL +.. _sequence: https://www.postgresql.org/docs/current/static/sql-createsequence.html + Test database templates ----------------------- diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt index 31fde97d1e..c327b0e9e7 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -426,6 +426,9 @@ happens. Explicitly specifying auto-primary-key values is mostly useful for bulk-saving objects, when you're confident you won't have primary-key collision. +If you're using PostgreSQL, the sequence associated with the primary key might +need to be updated; see :ref:`manually-specified-autoincrement-pk`. + What happens when you save? ---------------------------