Alpha

These pages are built from turborel-js’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Cursors

NAME

Client.cursor, PreparedStatement.cursor, Cursor: a query's rows as an async iterator, read by for await.

SYNOPSIS

const DEFAULT_CURSOR_BATCH = 100;

class Cursor implements AsyncIterable<readonly Value[]> {
  readonly columns: readonly ResultColumn[];
  next(): Promise<readonly Value[] | undefined>;
  [Symbol.asyncIterator](): AsyncGenerator<readonly Value[]>;
  close(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}

DESCRIPTION

A cursor opens with its first batch of rows, batch of them, 100 unless told, and fetches the next batch as the rows before it are taken, so a result of any size is held a batch at a time. for await reads its rows; leaving the loop early, or close, or await using, closes it. next gives one row at a time, undefined once all are read, the cursor then closed. A cursor of Client.cursor has a statement of its own, destroyed as it closes; one of a prepared statement leaves the statement prepared.

A cursor is read within its transaction. Under autocommit, the server granting fetch-ends, the transaction ends as the cursor does: the fetch of its last row commits it, closing it commits it, a fetch that fails rolls it back.

ERRORS

SQLSTATE SQLCODE When
24000 -501 A prepared statement's cursor opened while another of it is open
TB920 -920 A fetch cancelled by the cursor's signal

EXAMPLES

import { connect } from 'turborel';

await using conn = await connect('turborel://ann@127.0.0.1:7422/?tls_mode=disable');
await conn.query('CREATE TABLE NUMBERS (N INTEGER)');
await conn.query('INSERT INTO NUMBERS VALUES (1), (2), (3), (4), (5)');
let sum = 0n;
for await (const [n] of await conn.cursor('SELECT N FROM NUMBERS WHERE N > ? ORDER BY N', [1n], { batch: 2 })) {
  sum += n;
  if (n === 4n) break;
}
console.log(sum);
await conn.commit();
// 9n

SEE ALSO

Connections, Prepared Statements