docs(backends): explain how to release a cursor and suggest using `.s…

…ql` instead

ibis/backends/base/sql/__init__.py

@@ -127,14 +127,46 @@ def _get_schema_using_query(self, query):
         raise NotImplementedError(f"Backend {self.name} does not support .sql()")
 
     def raw_sql(self, query: str):
-        """Execute a query string.
+        """Execute a query string and return the cursor used for execution.
 
-        !!! warning "The returned cursor object must be **manually** released if results are returned."
+        !!! tip "Consider using [`.sql`][ibis.backends.base.sql.BaseSQLBackend.sql] instead"
+
+            If your query is a SELECT statement, you should use the
+            [`.sql`][ibis.backends.base.sql.BaseSQLBackend.sql] method to avoid
+            having to release the cursor returned from this method manually.
+
+            ??? warning "The returned cursor object must be **manually released** if you use `raw_sql`."
+
+                To release a cursor, call the `close` method on the returned cursor object.
+
+                You can close the cursor by explicitly calling its `close` method:
+
+                ```python
+                cursor = con.raw_sql("SELECT ...")
+                cursor.close()
+                ```
+
+                Or you can use a context manager:
+
+                ```python
+                with con.raw_sql("SELECT ...") as cursor:
+                    ...
+                ```
 
         Parameters
         ----------
         query
             DDL or DML statement
+
+        Examples
+        --------
+        >>> con = ibis.connect("duckdb://")
+        >>> with con.raw_sql("SELECT 1") as cursor:
+        ...     result = cursor.fetchall()
+        >>> result
+        [(1,)]
+        >>> cursor.closed
+        True
         """
         return self.con.execute(query)
 

ibis/backends/base/sql/alchemy/__init__.py

@@ -578,16 +578,7 @@ def _handle_failed_column_type_inference(
                 )
         return table
 
-    def raw_sql(self, query) -> None:
-        """Execute a query string.
-
-        !!! warning "The returned cursor object must be **manually** released."
-
-        Parameters
-        ----------
-        query
-            DDL or DML statement
-        """
+    def raw_sql(self, query):
         return self.con.connect().execute(
             sa.text(query) if isinstance(query, str) else query
         )