sql.cursor

import sql.cursor

sql lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled sql.cursor.* needs import sql.cursor.

Reading a result without holding all of it.

query() builds the whole result in memory, which is the right thing for the hundreds of rows most queries return and the wrong thing for the millions some do. A cursor reads the same result a row at a time, so the memory a loop needs is the size of one row rather than of the table.

var cursor = db.stream('select * from events')

for row in cursor {
  handle(row)
}

Running to the end closes the cursor. A loop that stops early does not, so anything that might break should close it, which using makes hard to forget.

Classes

Cursor

class sql.Cursor

A result being read a row at a time.

• printable — has a @to_string(), so echo and print() show something useful
• iterable — can be walked with for and iter

Constructor

sql.Cursor(cursor)

Parameters

• cursor (DriverCursor) — The adapter’s own cursor.

Cursor.columns()

sql.Cursor.columns() -> list[dict]

The result’s columns, each a dictionary with name and type.

Returns list[dict]

Cursor.column_names()

sql.Cursor.column_names() -> list[string]

The names of the result’s columns, in order.

Returns list[string]

Cursor.position()

sql.Cursor.position() -> number

How many rows have been read so far.

Returns number

Cursor.next()

sql.Cursor.next() -> dict|nil

The next row as a dictionary keyed by column name, or nil once the result is finished.

Returns dict|nil

Raises ClosedError if the cursor was closed.

Cursor.take()

sql.Cursor.take(count: number) -> list[dict]

The next count rows, or fewer at the end of the result.

For work that batches naturally: inserting a thousand rows at a time into somewhere else, say.

Parameters

• count (number)

Returns list[dict]

Cursor.rest()

sql.Cursor.rest() -> list[dict]

Reads whatever is left into a list.

This gives up the point of a cursor, so it is for the case where a result turned out to be small after all.

Returns list[dict]

Cursor.is_closed()

sql.Cursor.is_closed() -> bool

Whether the cursor has been closed or read to the end.

Returns bool

Cursor.close()

sql.Cursor.close()

Releases the cursor. Safe to call more than once.

Cursor.to_string()

sql.Cursor.to_string()

2026, Richard Ore and Zuri contributors