[1.8.x] Fixed #25371 -- Added reverse_sql and reverse_code examples to docs.

Backport of 4283a038431ef6428d086d4911179bd8eb8b2299 from master

1 files changed, 21 insertions, 3 deletions

diff --git a/docs/ref/migration-operations.txt b/docs/ref/migration-operations.txt
index dc6c90a30a..7f8302fc68 100644
--- a/docs/ref/migration-operations.txt
+++ b/docs/ref/migration-operations.txt
@@ -228,6 +228,14 @@ queries and parameters in the same way as :ref:`cursor.execute()
 If you want to include literal percent signs in the query, you have to double
 them if you are passing parameters.
 
+The ``reverse_sql`` queries are executed when the migration is unapplied, so
+you can reverse the changes done in the forwards queries::
+
+    migrations.RunSQL(
+        ["INSERT INTO musician (name) VALUES (%s);", ['Reinhardt']],
+        ["DELETE FROM musician where name=%s;", ['Reinhardt']],
+    )
+
 The ``state_operations`` argument is so you can supply operations that are
 equivalent to the SQL in terms of project state; for example, if you are
 manually creating a column, you should pass in a list containing an ``AddField``
@@ -274,6 +282,10 @@ match the operation's place in the project history, and the second is an
 instance of :class:`SchemaEditor
 <django.db.backends.base.schema.BaseDatabaseSchemaEditor>`.
 
+The ``reverse_code`` argument is called when unapplying migrations. This
+callable should undo what is done in the ``code`` callable so that the
+migration is reversible.
+
 The optional ``hints`` argument will be passed as ``**hints`` to the
 :meth:`allow_migrate` method of database routers to assist them in making a
 routing decision. See :ref:`topics-db-multi-db-hints` for more details on
@@ -301,14 +313,20 @@ model::
             Country(name="France", code="fr"),
         ])
 
+    def reverse_func(apps, schema_editor):
+        # forwards_func() creates two Country instances,
+        # so reverse_func() should delete them.
+        Country = apps.get_model("myapp", "Country")
+        db_alias = schema_editor.connection.alias
+        Country.objects.using(db_alias).filter(name="USA", code="us").delete()
+        Country.objects.using(db_alias).filter(name="France", code="fr").delete()
+
     class Migration(migrations.Migration):
 
         dependencies = []
 
         operations = [
-            migrations.RunPython(
-                forwards_func,
-            ),
+            migrations.RunPython(forwards_func, reverse_func),
         ]
 
 This is generally the operation you would use to create