Fixed #17448 -- Improved test and documented raw-sql gis query

django/contrib/gis/tests/geoapp/tests.py

@@ -189,7 +189,9 @@ class GeoModelTest(TestCase):
     def test_raw_sql_query(self):
         "Testing raw SQL query."
         cities1 = City.objects.all()
-        cities2 = City.objects.raw('select * from geoapp_city')
+        # Only PostGIS would support a 'select *' query because of its recognized
+        # HEXEWKB format for geometry fields
+        cities2 = City.objects.raw('select id, name, asText(point) from geoapp_city')
         self.assertEqual(len(cities1), len(list(cities2)))
         self.assertTrue(isinstance(cities2[0].point, Point))
 

docs/ref/contrib/gis/tutorial.txt

@@ -671,6 +671,17 @@ of abstraction::
 
 __ http://spatialreference.org/ref/epsg/32140/
 
+.. admonition:: Raw queries
+
+    When using :doc:`raw queries </topics/db/sql>`, you should generally wrap
+    your geometry fields with the ``asText()`` SQL function so as the field
+    value will be recognized by GEOS::
+
+        City.objects.raw('SELECT id, name, asText(point) from myapp_city')
+
+    This is not absolutely required by PostGIS, but generally you should only
+    use raw queries when you know exactly what you are doing.
+
 Lazy Geometries
 ---------------
 Geometries come to GeoDjango in a standardized textual representation.  Upon