The new documentation: https://sqlite-utils.datasette.io/en/latest/python-api.html#executing-queries

That documentation section is pretty weak at the moment - here's the whole thing:

Executing queries

The db.execute() and db.executescript() methods provide wrappers around .execute() and .executescript() on the underlying SQLite connection. These wrappers log to the tracer function if one has been registered. python db = Database(memory=True) db["dogs"].insert({"name": "Cleo"}) db.execute("update dogs set name = 'Cleopaws'") You can pass parameters as an optional second argument, using either a list or a dictionary. These will be correctly quoted and escaped. ```python

Using ? and a list:

db.execute("update dogs set name = ?", ["Cleopaws"])

Or using :name and a dictionary:

db.execute("update dogs set name = :name", {"name": "Cleopaws"}) ```

• Talks about .execute() - I want to talk about .query() instead
• Doesn't clarify that .execute() returns a Cursor - and assumes you know what to do with one
• Doesn't show an example of a select query at all
• The "tracer function" bit is confusing (should at least link to docs further down)
• For UPDATE should show how to access the number of rows modified (probably using .execute() there)

It does at least cover the two types of parameters, though that could be bulked out.

Still needs documentation, which will involve rewriting the whole Executing queries section.

The Python docs say: https://docs.python.org/3/library/sqlite3.html

To retrieve data after executing a SELECT statement, you can either treat the cursor as an iterator, call the cursor’s fetchone() method to retrieve a single matching row, or call fetchall() to get a list of the matching rows.

Looking at the C source code, both fetchmany() and fetchall() work under the hood by assembling a Python list: https://github.com/python/cpython/blob/be1cb3214d09d4bf0288bc45f3c1f167f67e4514/Modules/_sqlite/cursor.c#L907-L972 - see calls to PyList_Append()

So it looks like the most efficient way to iterate over a cursor may well be for row in cursor: - which I think calls this C function: https://github.com/python/cpython/blob/be1cb3214d09d4bf0288bc45f3c1f167f67e4514/Modules/_sqlite/cursor.c#L813-L876

One small problem with the existing method: https://github.com/simonw/sqlite-utils/blob/8cedc6a8b29180e68326f6b76f249d5e39e4b591/sqlite_utils/db.py#L362-L365

It returns a full list, but what if the user would rather have a generator they can iterate over without loading the results into memory in one go?

Potential names:

• db.query(sql) - it's weird to have both this and db.execute() but it is at least short and memorable
• db.sql(sql)
• db.execute_d(sql) - ugly
• db.execute_dicts(sql) - confusing
• db.execute_sql(sql) - easily confused with db.execute(sql)

I think db.query(sql) may be the best option here.