[2.0.x] Fixed #28632 -- Updated docs about using raw SQL with GIS and doc'd changes from refs #28518 in release notes.

Backport of 8869142a4d5b069c61781c0e4c5fdc971b017949 from master

1 files changed, 11 insertions, 6 deletions

diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt
index 10f97333cc..dd043077f9 100644
--- a/docs/ref/contrib/gis/tutorial.txt
+++ b/docs/ref/contrib/gis/tutorial.txt
@@ -645,16 +645,21 @@ of abstraction::
 
 __ http://spatialreference.org/ref/epsg/32140/
 
+.. _gis-raw-sql:
+
 .. admonition:: Raw queries
 
-    When using :doc:`raw queries </topics/db/sql>`, you should generally wrap
-    your geometry fields with the ``asText()`` SQL function (or ``ST_AsText``
-    for PostGIS) so that the field value will be recognized by GEOS::
+    When using :doc:`raw queries </topics/db/sql>`, you must wrap your geometry
+    fields so that the field value can be recognized by GEOS::
+
+        from django.db import connection
+        # or if you're querying a non-default database:
+        from django.db import connections
+        connection = connections['your_gis_db_alias']
 
-        City.objects.raw('SELECT id, name, asText(point) from myapp_city')
+        City.objects.raw('SELECT id, name, %s as point from myapp_city' % (connection.ops.select % 'point'))
 
-    This is not absolutely required by PostGIS, but generally you should only
-    use raw queries when you know exactly what you are doing.
+    You should only use raw queries when you know exactly what you're doing.
 
 Lazy Geometries
 ---------------