Refs #33342 -- Deprecated ExclusionConstraint.opclasses.

3 files changed, 51 insertions, 12 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 3a3abfeb42..939bc5049e 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -72,6 +72,9 @@ details on these changes.
 * The ``name`` argument of ``django.utils.functional.cached_property()`` will
   be removed.
 
+* The ``opclasses`` argument of
+  ``django.contrib.postgres.constraints.ExclusionConstraint`` will be removed.
+
 .. _deprecation-removed-in-4.1:
 
 4.1
diff --git a/docs/ref/contrib/postgres/constraints.txt b/docs/ref/contrib/postgres/constraints.txt
index fe7d53bb79..1ea1fcfb8f 100644
--- a/docs/ref/contrib/postgres/constraints.txt
+++ b/docs/ref/contrib/postgres/constraints.txt
@@ -53,10 +53,22 @@ operators with strings. For example::
 
     Only commutative operators can be used in exclusion constraints.
 
+The :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` expression can
+be used to specify a custom `operator class`_ for the constraint expressions.
+For example::
+
+    expressions=[
+        (OpClass('circle', name='circle_ops'), RangeOperators.OVERLAPS),
+    ]
+
+creates an exclusion constraint on ``circle`` using ``circle_ops``.
+
 .. versionchanged:: 4.1
 
     Support for the ``OpClass()`` expression was added.
 
+.. _operator class: https://www.postgresql.org/docs/current/indexes-opclass.html
+
 ``index_type``
 --------------
 
@@ -147,19 +159,11 @@ For example::
 
 creates an exclusion constraint on ``circle`` using ``circle_ops``.
 
-Alternatively, you can use
-:class:`OpClass() <django.contrib.postgres.indexes.OpClass>` in
-:attr:`~ExclusionConstraint.expressions`::
-
-    ExclusionConstraint(
-        name='exclude_overlapping_opclasses',
-        expressions=[(OpClass('circle', 'circle_ops'), RangeOperators.OVERLAPS)],
-    )
-
-.. versionchanged:: 4.1
+.. deprecated:: 4.1
 
-    Support for specifying operator classes with the ``OpClass()`` expression
-    was added.
+    The ``opclasses`` parameter is deprecated in favor of using
+    :class:`OpClass() <django.contrib.postgres.indexes.OpClass>` in
+    :attr:`~ExclusionConstraint.expressions`.
 
 Examples
 --------
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index d9a05f3bda..11d2c5ca04 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -353,6 +353,38 @@ Miscellaneous
 * The ``name`` argument of :func:`django.utils.functional.cached_property` is
   deprecated as it's unnecessary as of Python 3.6.
 
+* The ``opclasses`` argument of
+  ``django.contrib.postgres.constraints.ExclusionConstraint`` is deprecated in
+  favor of using :class:`OpClass() <django.contrib.postgres.indexes.OpClass>`
+  in :attr:`.ExclusionConstraint.expressions`. To use it, you need to add
+  ``'django.contrib.postgres'`` in your :setting:`INSTALLED_APPS`.
+
+  After making this change, :djadmin:`makemigrations` will generate a new
+  migration with two operations: ``RemoveConstraint`` and ``AddConstraint``.
+  Since this change has no effect on the database schema,
+  the :class:`~django.db.migrations.operations.SeparateDatabaseAndState`
+  operation can be used to only update the migration state without running any
+  SQL. Move the generated operations into the ``state_operations`` argument of
+  :class:`~django.db.migrations.operations.SeparateDatabaseAndState`. For
+  example::
+
+    class Migration(migrations.Migration):
+        ...
+
+        operations = [
+            migrations.SeparateDatabaseAndState(
+                database_operations=[],
+                state_operations=[
+                    migrations.RemoveConstraint(
+                        ...
+                    ),
+                    migrations.AddConstraint(
+                        ...
+                    ),
+                ],
+            ),
+        ]
+
 Features removed in 4.1
 =======================