diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index 382ce5c08a..f3ebee6a8d 100644 --- a/docs/ref/settings.txt +++ b/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 `. +.. 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