Browse Source

Refs #32674 -- Noted that auto-created through table PKs cannot be automatically migrated.

Carlton Gibson 3 years ago
parent
commit
907d3a7ff4
2 changed files with 30 additions and 0 deletions
  1. 25 0
      docs/ref/settings.txt
  2. 5 0
      docs/releases/3.2.txt

+ 25 - 0
docs/ref/settings.txt

@@ -1260,6 +1260,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``

+ 5 - 0
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