From 712ce47e1a55f7ebd96ac64201a4817ae4743216 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= Date: Sat, 17 Jun 2017 20:17:15 -0700 Subject: [PATCH] [1.11.x] Fixed #18485 -- Doc'd behavior of PostgreSQL when manually setting AutoField. Backport of 4f1eb64ad0bcebfae4075486855eb6b63355cc5a from master --- docs/ref/databases.txt | 27 +++++++++++++++++++++++++++ docs/ref/models/instances.txt | 3 +++ 2 files changed, 30 insertions(+) diff --git a/docs/ref/databases.txt b/docs/ref/databases.txt index add34acb6c..76ead1024e 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 696e09ba57..4a63b016aa 100644 --- a/docs/ref/models/instances.txt +++ b/docs/ref/models/instances.txt @@ -437,6 +437,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? ---------------------------