Fixed #22423 -- Added support for MySQL operators on real geometries.

Thanks Viswanathan Mahalingam for the report and initial patch, and
Nicke Pope and Tim Graham for the review.

3 files changed, 64 insertions, 25 deletions

diff --git a/docs/ref/contrib/gis/db-api.txt b/docs/ref/contrib/gis/db-api.txt
index 9b88ff7861..1520f06d37 100644
--- a/docs/ref/contrib/gis/db-api.txt
+++ b/docs/ref/contrib/gis/db-api.txt
@@ -25,21 +25,15 @@ GeoDjango currently provides the following spatial database backends:
 MySQL Spatial Limitations
 -------------------------
 
-MySQL's spatial extensions only support bounding box operations
-(what MySQL calls minimum bounding rectangles, or MBR).  Specifically,
-`MySQL does not conform to the OGC standard
-<https://dev.mysql.com/doc/refman/en/spatial-relation-functions.html>`_:
+Before MySQL 5.6.1, spatial extensions only support bounding box operations
+(what MySQL calls minimum bounding rectangles, or MBR). Specifically, MySQL did
+not conform to the OGC standard. Django supports spatial functions operating on
+real geometries available in modern MySQL versions. However, the spatial
+functions are not as rich as other backends like PostGIS.
 
-    Currently, MySQL does not implement these functions
-    [``Contains``, ``Crosses``, ``Disjoint``, ``Intersects``, ``Overlaps``,
-    ``Touches``, ``Within``]
-    according to the specification.  Those that are implemented return
-    the same result as the corresponding MBR-based functions.
+.. versionchanged:: 3.0
 
-In other words, while spatial lookups such as :lookup:`contains <gis-contains>`
-are available in GeoDjango when using MySQL, the results returned are really
-equivalent to what would be returned when using :lookup:`bbcontains`
-on a different spatial backend.
+    Support for spatial functions operating on real geometries was added.
 
 .. warning::
 
diff --git a/docs/ref/contrib/gis/geoquerysets.txt b/docs/ref/contrib/gis/geoquerysets.txt
index 154d8736f8..e8a488a323 100644
--- a/docs/ref/contrib/gis/geoquerysets.txt
+++ b/docs/ref/contrib/gis/geoquerysets.txt
@@ -148,10 +148,15 @@ Backend     SQL Equivalent
 ==========  ============================
 PostGIS     ``ST_Contains(poly, geom)``
 Oracle      ``SDO_CONTAINS(poly, geom)``
-MySQL       ``MBRContains(poly, geom)``
+MySQL       ``ST_Contains(poly, geom)``
 SpatiaLite  ``Contains(poly, geom)``
 ==========  ============================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBRContains`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: contains_properly
 
 ``contains_properly``
@@ -233,7 +238,7 @@ SpatiaLite  ``Covers(poly, geom)``
 -----------
 
 *Availability*: `PostGIS <https://postgis.net/docs/ST_Crosses.html>`__,
-SpatiaLite, PGRaster (Conversion)
+MySQL, SpatiaLite, PGRaster (Conversion)
 
 Tests if the geometry field spatially crosses the lookup geometry.
 
@@ -245,9 +250,14 @@ Example::
 Backend     SQL Equivalent
 ==========  ==========================
 PostGIS     ``ST_Crosses(poly, geom)``
+MySQL       ``ST_Crosses(poly, geom)``
 SpatiaLite  ``Crosses(poly, geom)``
 ==========  ==========================
 
+.. versionchanged:: 3.0
+
+    MySQL support was added.
+
 .. fieldlookup:: disjoint
 
 ``disjoint``
@@ -267,10 +277,15 @@ Backend     SQL Equivalent
 ==========  =================================================
 PostGIS     ``ST_Disjoint(poly, geom)``
 Oracle      ``SDO_GEOM.RELATE(poly, 'DISJOINT', geom, 0.05)``
-MySQL       ``MBRDisjoint(poly, geom)``
+MySQL       ``ST_Disjoint(poly, geom)``
 SpatiaLite  ``Disjoint(poly, geom)``
 ==========  =================================================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBRDisjoint`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: equals
 
 ``equals``
@@ -290,10 +305,15 @@ Backend     SQL Equivalent
 ==========  =================================================
 PostGIS     ``ST_Equals(poly, geom)``
 Oracle      ``SDO_EQUAL(poly, geom)``
-MySQL       ``MBREquals(poly, geom)``
+MySQL       ``ST_Equals(poly, geom)``
 SpatiaLite  ``Equals(poly, geom)``
 ==========  =================================================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBREquals`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: exact
 .. fieldlookup:: same_as
 
@@ -303,8 +323,8 @@ SpatiaLite  ``Equals(poly, geom)``
 *Availability*: `PostGIS <https://postgis.net/docs/ST_Geometry_Same.html>`__,
 Oracle, MySQL, SpatiaLite, PGRaster (Bilateral)
 
-Tests if the geometry field is "equal" to the lookup geometry. On Oracle and
-SpatiaLite it tests spatial equality, while on MySQL and PostGIS it tests
+Tests if the geometry field is "equal" to the lookup geometry. On Oracle,
+MySQL, and SpatiaLite, it tests spatial equality, while on PostGIS it tests
 equality of bounding boxes.
 
 Example::
@@ -316,10 +336,15 @@ Backend     SQL Equivalent
 ==========  =================================================
 PostGIS     ``poly ~= geom``
 Oracle      ``SDO_EQUAL(poly, geom)``
-MySQL       ``MBREquals(poly, geom)``
+MySQL       ``ST_Equals(poly, geom)``
 SpatiaLite  ``Equals(poly, geom)``
 ==========  =================================================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBREquals`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: intersects
 
 ``intersects``
@@ -339,10 +364,15 @@ Backend     SQL Equivalent
 ==========  =================================================
 PostGIS     ``ST_Intersects(poly, geom)``
 Oracle      ``SDO_OVERLAPBDYINTERSECT(poly, geom)``
-MySQL       ``MBRIntersects(poly, geom)``
+MySQL       ``ST_Intersects(poly, geom)``
 SpatiaLite  ``Intersects(poly, geom)``
 ==========  =================================================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBRIntersects`` and operates only on
+    bounding boxes.
+
 .. fieldlookup:: isvalid
 
 ``isvalid``
@@ -379,10 +409,15 @@ Backend     SQL Equivalent
 ==========  ============================
 PostGIS     ``ST_Overlaps(poly, geom)``
 Oracle      ``SDO_OVERLAPS(poly, geom)``
-MySQL       ``MBROverlaps(poly, geom)``
+MySQL       ``ST_Overlaps(poly, geom)``
 SpatiaLite  ``Overlaps(poly, geom)``
 ==========  ============================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBROverlaps`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: relate
 
 ``relate``
@@ -464,11 +499,16 @@ Example::
 Backend     SQL Equivalent
 ==========  ==========================
 PostGIS     ``ST_Touches(poly, geom)``
-MySQL       ``MBRTouches(poly, geom)``
+MySQL       ``ST_Touches(poly, geom)``
 Oracle      ``SDO_TOUCH(poly, geom)``
 SpatiaLite  ``Touches(poly, geom)``
 ==========  ==========================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBRTouches`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: within
 
 ``within``
@@ -487,11 +527,16 @@ Example::
 Backend     SQL Equivalent
 ==========  ==========================
 PostGIS     ``ST_Within(poly, geom)``
-MySQL       ``MBRWithin(poly, geom)``
+MySQL       ``ST_Within(poly, geom)``
 Oracle      ``SDO_INSIDE(poly, geom)``
 SpatiaLite  ``Within(poly, geom)``
 ==========  ==========================
 
+.. versionchanged:: 3.0
+
+    In older versions, MySQL uses ``MBRWithin`` and operates only on bounding
+    boxes.
+
 .. fieldlookup:: left
 
 ``left``
diff --git a/docs/ref/contrib/gis/install/index.txt b/docs/ref/contrib/gis/install/index.txt
index 7adf85c8ce..924dec35f0 100644
--- a/docs/ref/contrib/gis/install/index.txt
+++ b/docs/ref/contrib/gis/install/index.txt
@@ -59,7 +59,7 @@ supported versions, and any notes for each of the supported database backends:
 Database            Library Requirements            Supported Versions  Notes
 ==================  ==============================  ==================  =========================================
 PostgreSQL          GEOS, GDAL, PROJ.4, PostGIS     9.5+                Requires PostGIS.
-MySQL               GEOS, GDAL                      5.6+                Not OGC-compliant; :ref:`limited functionality <mysql-spatial-limitations>`.
+MySQL               GEOS, GDAL                      5.6.1+              :ref:`Limited functionality <mysql-spatial-limitations>`.
 Oracle              GEOS, GDAL                      12.2+               XE not supported.
 SQLite              GEOS, GDAL, PROJ.4, SpatiaLite  3.8.3+              Requires SpatiaLite 4.3+
 ==================  ==============================  ==================  =========================================