[3.0.x] Fixed #28273 -- Doc'd fast nullable column creation with defaults.

Backport of 06909fe084f87a65459a83bd69d7cdbe4fce9a7c from master

1 files changed, 15 insertions, 0 deletions

diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index b5201b3219..f0436a1366 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -150,6 +150,21 @@ a default value to put into existing rows. It does not affect the behavior
 of setting defaults in the database directly - Django never sets database
 defaults and always applies them in the Django ORM code.
 
+.. warning::
+
+    On older databases, adding a field with a default value may cause a full
+    rewrite of the table. This happens even for nullable fields and may have a
+    negative performance impact. To avoid that, the following steps should be
+    taken.
+
+    * Add the nullable field without the default value and run the
+      :djadmin:`makemigrations` command. This should generate a migration with
+      an ``AddField`` operation.
+
+    * Add the default value to your field and run the :djadmin:`makemigrations`
+      command. This should generate a migration with an ``AlterField``
+      operation.
+
 ``RemoveField``
 ---------------