sql.statement

import sql.statement

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.statement.* needs import sql.statement.

A statement compiled once and run many times.

Every engine here splits running a statement into compiling it and executing it, and the compile is the expensive half. A statement run in a loop should pay for it once:

var insert = db.prepare('insert into points (x, y) values (?, ?)')

for point in points {
  insert.exec([point.x, point.y])
}

insert.close()

The placeholders are translated once, when the statement is prepared, so the loop does no string work at all.

Classes

Statement

class sql.Statement

A prepared statement.

• printable — has a @to_string(), so echo and print() show something useful

Constructor

sql.Statement(connection, statement, source, sql, style)

Parameters

• connection (Connection) — The connection that prepared this.
• statement (DriverStatement) — The adapter’s own statement.
• source (string) — The statement as it was written.
• sql (string) — The statement as the engine received it.
• style (string) — The driver’s placeholder style.

Statement.source()

sql.Statement.source() -> string

The statement as it was written, with ? or :name in it.

Returns string

Statement.sql()

sql.Statement.sql() -> string

The statement as the engine received it, with the engine’s own placeholders.

Returns string

Statement.columns()

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

The columns this statement returns, each a dictionary with name and type. Empty for a statement that returns no rows.

Returns list[dict]

Statement.parameter_count()

sql.Statement.parameter_count() -> number

How many parameters this statement binds.

Returns number

Statement.query()

sql.Statement.query(params) -> ResultSet

Runs the statement and reads its whole result.

Parameters

• params (list|dict|nil)

Returns ResultSet

Statement.exec()

sql.Statement.exec(params) -> ExecResult

Runs the statement for its effect.

Parameters

• params (list|dict|nil)

Returns ExecResult

Statement.stream()

sql.Statement.stream(params, options) -> Cursor

Runs the statement and returns a cursor over its result.

The cursor holds this statement until it closes, so the statement cannot be run again in the meantime.

Parameters

• params (list|dict|nil)
• options (dict|nil) — { batch } on engines that fetch in batches; ignored where the engine streams already.

Returns Cursor

Statement.fetch_one()

sql.Statement.fetch_one(params) -> dict|nil

The first row, or nil when the statement returns none.

Parameters

• params (list|dict|nil)

Returns dict|nil

Statement.fetch_all()

sql.Statement.fetch_all(params) -> list[dict]

Every row, as dictionaries.

Parameters

• params (list|dict|nil)

Returns list[dict]

Statement.fetch_value()

sql.Statement.fetch_value(params, fallback) -> any

The first column of the first row.

Parameters

• params (list|dict|nil)
• fallback (any) — What to return when the statement returns no rows.

Returns any

Statement.close()

sql.Statement.close()

Releases the statement. Safe to call more than once.

Statement.is_closed()

sql.Statement.is_closed() -> bool

Whether this statement has been closed.

Returns bool

Statement.to_string()

sql.Statement.to_string()

2026, Richard Ore and Zuri contributors