[Django] #37031: Improve "Writing migrations" how-to -- unique fields and ManyToManyField through models

[Django]

#37031: Improve "Writing migrations" how-to -- unique fields and ManyToManyField
through models
-----------------------------------------+-------------------------------
Reporter: Clifford Gama | Owner: Clifford Gama
Type: Bug | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Keywords: migrations
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-----------------------------------------+-------------------------------
In the writing migrations docs there are two advanced migration scenarios
that have inaccuracies and could be made clearer.

**Migrations that add unique fields**

1. The current approach splits the work across three files: one to add the
field, one to populate values, and one to restore the constraint. All
three operations can be placed in a single migration, which is simpler to
follow and has the added benefit of being atomic — removing the race
condition that is currently warned about in the docs.

2. I think the section should mention that `Field.db_default` avoids this
problem entirely by having the database generate a unique value per row.
This is worth noting upfront so readers can choose the simpler path where
their use case allows.

3. No mention of performant alternatives for large tables: The `RunPython`
example iterates row by row with individual saves. For large tables this
will be very slow. The docs should note that `QuerySet.bulk_update()` or
RunSQL are worth considering in that case.

**Changing a ManyToManyField to use a through model**

1. Inaccurate description of how Django handles this change: The section
states that "the default migration will delete the existing table and
create a new one". This is not accurate. Django
[https://github.com/django/django/blob/d61f33f03b3177afdf1d76153014bad4107b1224/django/db/backends/base/schema.py#L894
refuses to apply a migration] when `through=` is added/changed on an
existing `ManyToManyField`.

2. The through model example does not accurately reflect the database: The
current example uses `on_delete=DO_NOTHING` and `models.UniqueConstraint`,
whereas Django's auto-generated through tables use `CASCADE` and
`unique_together`. Since the state and database are not in sync, I think
this could cause issues in later migrations.

3. The example can be simplified by setting `Meta.db_table` on the new
through model to match the existing table name, eliminating the need for a
`RunSQL` rename operation.

The section also suggests using `sqlmigrate` or `dbshell` to find the
existing table name, which is indirect. The simplest approach is to
inspect `field.through._meta.db_table` before modifying the field.
--
Ticket URL: <https://code.djangoproject.com/ticket/37031>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#37031: Improve "Writing migrations" how-to -- unique fields and ManyToManyField
through models

-------------------------------+-----------------------------------------

Reporter: Clifford Gama | Owner: Clifford Gama
Type: Bug | Status: assigned
Component: Documentation | Version: 6.0

Severity: Normal | Resolution:

Keywords: migrations | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------+-----------------------------------------
Changes (by MANAS MADESHIYA):

* cc: MANAS MADESHIYA (added)

--
Ticket URL: <https://code.djangoproject.com/ticket/37031#comment:1>

[Django]

#37031: Improve "Writing migrations" how-to -- unique fields and ManyToManyField
through models
-------------------------------+-----------------------------------------
Reporter: Clifford Gama | Owner: Clifford Gama
Type: Bug | Status: assigned
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: migrations | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Changes (by Sarah Boyce):

* cc: Shai Berger, Markus Holtermann (added)

Comment:

The docs on "Migrations that add unique fields" was added as part of
#23932, I will cc some folks involved in that ticket in case they want to
add their opinion

Clifford please can you split this into 2 tickets? Repurpose this ticket
only for the "Migrations that add unique fields" suggested changes and a
new ticket for "Changing a ManyToManyField to use a through model"
suggested changes
--
Ticket URL: <https://code.djangoproject.com/ticket/37031#comment:2>