From bac416972df546ac58febd3990b2107d60d7f166 Mon Sep 17 00:00:00 2001
From: Carlton Gibson <carlton.gibson@noumenal.es>
Date: Thu, 29 Apr 2021 10:59:14 +0200
Subject: [PATCH] [3.2.x] Refs #32674 -- Noted that auto-created through table
 PKs cannot be automatically migrated.

Backport of 907d3a7ff4e12ad4ccc86af26a728007fe4d6fa2 from main
---
 docs/ref/settings.txt | 25 +++++++++++++++++++++++++
 docs/releases/3.2.txt |  5 +++++
 2 files changed, 30 insertions(+)

diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt
index 5fdb76b2d0..abbff39c45 100644
--- a/docs/ref/settings.txt
+++ b/docs/ref/settings.txt
@@ -1257,6 +1257,31 @@ Default: ``'``:class:`django.db.models.AutoField`\ ``'``
 Default primary key field type to use for models that don't have a field with
 :attr:`primary_key=True <django.db.models.Field.primary_key>`.
 
+.. admonition:: Migrating auto-created through tables
+
+    The value of ``DEFAULT_AUTO_FIELD`` will be respected when creating new
+    auto-created through tables for many-to-many relationships.
+
+    Unfortunately, the primary keys of existing auto-created through tables
+    cannot currently be updated by the migrations framework.
+
+    This means that if you switch the value of ``DEFAULT_AUTO_FIELD`` and then
+    generate migrations, the primary keys of the related models will be
+    updated, as will the foreign keys from the through table, but the primary
+    key of the auto-created through table will not be migrated.
+
+    In order to address this, you should add a
+    :class:`~django.db.migrations.operations.RunSQL` operation to your
+    migrations to perform the required ``ALTER TABLE`` step. You can check the
+    existing table name through ``sqlmigrate``, ``dbshell``, or with the
+    field’s ``remote_field.through._meta.db_table`` property.
+
+    Explicitly defined through models are already handled by the migrations
+    system.
+
+    Allowing automatic migrations for the primary key of existing auto-created
+    through tables :ticket:`may be implemented at a later date <32674>`.
+
 .. setting:: DEFAULT_CHARSET
 
 ``DEFAULT_CHARSET``
diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index c1447593fd..828add0fea 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -95,6 +95,11 @@ or on a per-model basis::
 In anticipation of the changing default, a system check will provide a warning
 if you do not have an explicit setting for :setting:`DEFAULT_AUTO_FIELD`.
 
+When changing the value of :setting:`DEFAULT_AUTO_FIELD`, migrations for the
+primary key of existing auto-created through tables cannot be generated
+currently. See the :setting:`DEFAULT_AUTO_FIELD` docs for details on migrating
+such tables.
+
 .. _new_functional_indexes:
 
 Functional indexes