docs: explain you only need to close a conn.raw_sql() if you are running a query that returns results

[NickCrews]

Please describe the issue

I was following the advise of https://ibis-project.org/how-to/extending/sql#backend.raw_sql, and closing the returned cursor.

But the actual SQL I was running was an EXPLAIN SELECT ... query. I was getting errors, eventually after a lot of headscratching I think I have found that I do NOT want to close the cursor after this query.

Possible actions:

1. be more precise with what sorts of SQL statements require the close.
2. make it so ALL queries require a close, so there is no distinction.
3. UX: make the returned object itself closable, so I don't have to do from contextlib import closing and I can just do with conn.raw_sql(x) as cursor:

Code of Conduct

• I agree to follow this project's Code of Conduct

[cpcloud]

@NickCrews Thanks for the issue!

I think option 1 is probably the best we can do here without a ton of additional effort.

make it so ALL queries require a close, so there is no distinction.

This is out of the control of Ibis. There's no agreed-upon-by-all-backends criteria for whether a cursor needs to be closed. The documentation is best effort. I can certainly update it to reflect the variation.

make the returned object itself closable

We're unlikely to do this because it would require wrapping the backend's cursor, and the point of raw_sql is to expose the backend's cursor directly, without interfering. The trade off is that users must now deal with any inconveniences brought on by the backend's driver.

[cpcloud]

To clarify, you should only need to close the cursor if you're doing a SELECT statement, or more generally a statement that can return values. DDL statements should not require closing the cursor.