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.

Connections

NAME

connect, Client: a connection of the driver's standard interface, a Promise-based API for Node.js, with TypeScript types.

SYNOPSIS

function connect(settings: string | ConnectOptions): Promise<Client>;
type ConnectOptions = { [setting: string]?: string | number | boolean; autocommit?: boolean };

class Client {
  readonly connection: Connection;
  query(sql: string, params?: readonly Value[], options?: { signal?: AbortSignal }): Promise<Result>;
  prepare(sql: string): Promise<PreparedStatement>;
  cursor(sql: string, params?: readonly Value[], options?: { batch?: number; signal?: AbortSignal }): Promise<Cursor>;
  autocommit: boolean;
  readonly inTransaction: boolean;
  commit(): Promise<void>;
  rollback(): Promise<void>;
  transaction<T>(work: (client: Client) => Promise<T>): Promise<T>;
  readLob(lob: Lob | LobLocator): Readable;
  writeLob(kind: 'character' | 'binary', source: AsyncIterable<Uint8Array | string> | Iterable<Uint8Array | string>): Promise<LobLocator>;
  readonly closed: boolean;
  close(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}

interface ResultColumn extends Column {
  readonly typeName: string;
  readonly typeWritten: string;
}

interface Result {
  readonly rows: readonly (readonly Value[])[];
  readonly columns: readonly ResultColumn[];
  readonly rowCount: bigint | undefined;
  readonly completion: Completion | undefined;
}

DESCRIPTION

connect connects as a turborel:// URI, or options named as its settings are (Appendix C), say, and gives a Client; autocommit among the options sets it on.

query runs a statement; with params, its ? take them in order, by a statement prepared for it and destroyed after. Its Result gives a query's rows and columns, or another statement's completion, and rowCount, the rows the server counted, where it counts them. Each of its columns, as a prepared statement's and a cursor's, is the low-level client's Column with its typeName, as the Information Schema's DATA_TYPE gives it, and typeWritten, the type as SQL writes it: as the column was declared where the server told it, so INTEGER and DECIMAL(9,2), else as its type's tag says, so NUMERIC(10,0) (Statements and Cursors). prepare gives a prepared statement, and cursor a cursor of a query's rows.

A transaction begins with the first statement and lasts until commit or rollback; under autocommit each statement is its own. transaction(work) runs work in a transaction of its own, autocommit off within it: committed as it succeeds, rolled back as it fails.

readLob gives a large object's octets as a Node.js readable stream; writeLob writes one from a stream, or any iterable of octets or text, and gives its locator to pass as a parameter.

An AbortSignal given as signal cancels its statement as it aborts: the statement fails with SQLCODE -920 and SQLSTATE TB920, and the connection goes on; one aborted before the statement is sent fails with the same codes, and nothing is sent.

A client runs one operation at a time, in the order asked, so concurrent calls of one client wait their turn. close, or await using, ends the connection once its operations are done. connection gives the low-level client beneath it, for what the standard interface has no place for: copies, pipelines, notices, settings told.

ERRORS

SQLSTATE SQLCODE When
TB920 -920 The statement was cancelled by its signal
TB910 -910 An operation of a client closed
25000 -917 transaction while a transaction is active
08001 -919 Settings that cannot be read, or by which no connection is made

The statement's own failures are the server's, as it reports them.

EXAMPLES

import { connect } from 'turborel';

await using conn = await connect({ host: '127.0.0.1', port: 7422, user: 'ann', tls_mode: 'disable' });
await conn.query('CREATE TABLE STAFF (ID INTEGER PRIMARY KEY, NAME VARCHAR(20))');
await conn.commit();
await conn.transaction(async (tx) => {
  await tx.query('INSERT INTO STAFF VALUES (?, ?)', [1n, 'Ada']);
  await tx.query('INSERT INTO STAFF VALUES (?, ?)', [2n, 'Grace']);
});
const inserted = await conn.query("INSERT INTO STAFF VALUES (3, 'Edsger')");
console.log(inserted.rowCount, inserted.completion.sqlstate, conn.inTransaction);
await conn.rollback();
console.log((await conn.query('SELECT COUNT(*) FROM STAFF')).rows);
try {
  await conn.query('VALUES 1', [], { signal: AbortSignal.abort() });
} catch (e) {
  console.log(e.sqlcode, e.sqlstate);
}
// 1n 00000 true
// [ [ 2n ] ]
// -920 TB920

SEE ALSO

Installing, Prepared Statements, Cursors, Pools, Connections