docs(sql): emphasize the need to close a raw_sql cursor only when using SELECT statements

Author: cpcloud

ibis/backends/base/sql/__init__.py

@@ -136,12 +136,16 @@ def raw_sql(self, query: str):
         ::: {.callout-tip}
         ## Consider using [`.sql`](#ibis.backends.base.sql.BaseSQLBackend.sql) instead
 
-        If your query is a SELECT statement, you should use the
+        If your query is a `SELECT` statement you can use the
         [backend `.sql`](#ibis.backends.base.sql.BaseSQLBackend.sql) method to avoid
-        having to release the cursor returned from this method manually.
+        having to manually release the cursor returned from this method.
 
-        ::: {.callout-warning collapse="true"}
-        ## The returned cursor object must be **manually released** if you use `raw_sql`.
+        ::: {.callout-warning}
+        ## The cursor returned from this method must be **manually released**
+
+        You **do not** need to call `.close()` on the cursor when running DDL
+        or DML statements like `CREATE`, `INSERT` or `DROP`, only when using
+        `SELECT` statements.
 
         To release a cursor, call the `close` method on the returned cursor
         object.
@@ -166,7 +170,7 @@ def raw_sql(self, query: str):
         Parameters
         ----------
         query
-            DDL or DML statement
+            SQL query string
 
         Examples
         --------

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

@@ -589,7 +589,59 @@ def _handle_failed_column_type_inference(
                 )
         return table
 
-    def raw_sql(self, query):
+    def raw_sql(self, query: str | sa.sql.ClauseElement):
+        """Execute a query and return the cursor used for execution.
+
+        ::: {.callout-tip}
+        ## Consider using [`.sql`](#ibis.backends.base.sql.BaseSQLBackend.sql) instead
+
+        If your query is a `SELECT` statement you can use the
+        [backend `.sql`](#ibis.backends.base.sql.BaseSQLBackend.sql) method to avoid
+        having to manually release the cursor returned from this method.
+
+        ::: {.callout-warning}
+        ## The cursor returned from this method must be **manually released**
+
+        You **do not** need to call `.close()` on the cursor when running DDL
+        or DML statements like `CREATE`, `INSERT` or `DROP`, only when using
+        `SELECT` statements.
+
+        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
+            SQL query or SQLAlchemy expression to execute
+
+        Examples
+        --------
+        >>> con = ibis.connect("duckdb://")
+        >>> with con.raw_sql("SELECT 1") as cursor:
+        ...     result = cursor.fetchall()
+        ...
+        >>> result
+        [(1,)]
+        >>> cursor.closed
+        True
+        """
         return self.con.connect().execute(
             sa.text(query) if isinstance(query, str) else query
         )