From 4f1eb64ad0bcebfae4075486855eb6b63355cc5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20Freitag?= <mail@franek.fr>
Date: Sat, 17 Jun 2017 20:17:15 -0700
Subject: [PATCH] Fixed #18485 -- Doc'd behavior of PostgreSQL when manually
 setting AutoField.

---
 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 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)
+    <User: alice>
+    >>> # 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?
 ---------------------------