@eltjs/sdk-microsoft-sql-server 0.1.3 → 0.3.0

package/README.md

@@ -18,6 +18,7 @@ for (const table of await session.tables()) {
 - `SqlServerDatabase` takes an ADO.NET connection string. The string must name its server and its database. An `mssql://` URL does not work.
 - `open` gives a `SqlServerSession`. Dispose the session to close its connections.
 - `tables` gives each user table that the login can read. A view is not in the list. Each `SqlServerTable` has its columns, its primary key and its Change Tracking state. `unreadable` names the columns that the login cannot read.
+- `rows`, `page`, `rowversions` and `changes` take a `SqlServerRead`: a `clock`, which an app gives as `globalThis`, and a `signal`, which stops the read also when the server sends nothing. A read that gets no row between two checks an hour apart fails with `SqlServerUnavailableError`.
 - `rows`, `page` and `rowversions` read rows of a table. `changes` gives the rows that changed after a `ChangePosition`, each row once.
 - `version`, `statistics`, `rowCounts` and `lastWrites` give the values that show that a table changed.
 

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export { type ChangePosition, type SqlServerChange } from './change-set.ts';
 export { ChangeHistoryExpiredError, SqlServerLoginError, SqlServerPermissionError, SqlServerUnavailableError, SqlServerVersionError, } from './errors.ts';
 export { SqlServerColumn } from './sql-server-column.ts';
 export { SqlServerDatabase } from './sql-server-database.ts';
+export { type SqlServerRead } from './sql-server-request.ts';
 export { SqlServerRow } from './sql-server-row.ts';
 export { SqlServerSession } from './sql-server-session.ts';
 export { SqlServerTable } from './sql-server-table.ts';

package/dist/sql-server-database.js

@@ -1,7 +1,7 @@
 import sql from 'mssql';
 import { cellNumber } from './cells.js';
-import { SqlServerLoginError, SqlServerUnavailableError, SqlServerVersionError, } from './errors.js';
-import { query } from './sql-server-request.js';
+import { SqlServerVersionError } from './errors.js';
+import { connectionFailure, query } from './sql-server-request.js';
 import { SqlServerSession } from './sql-server-session.js';
 // One database on a SQL Server, named by an ADO.NET connection string
 // (Server=host,port;Database=name;User Id=...;Password=...), the form SQL
@@ -23,7 +23,12 @@ export class SqlServerDatabase {
         this.location = `${config.server}${instance ? `\\${instance}` : ''}:${config.port ?? 1433}/${config.database}`;
         this.name = config.database;
         // A read streams a whole table, so no time limit fits every table.
-        this.#config = { ...config, requestTimeout: 0, pool: { min: 0, max: 4 } };
+        this.#config = {
+            ...config,
+            requestTimeout: 0,
+            pool: { min: 0, max: 4 },
+            beforeConnect: markBusyLogin,
+        };
         Object.freeze(this);
     }
     async open() {
@@ -32,12 +37,10 @@ export class SqlServerDatabase {
             await pool.connect();
         }
         catch (cause) {
-            throw refused(cause)
-                ? new SqlServerLoginError(this.location, cause)
-                : new SqlServerUnavailableError(this.location, cause);
+            throw connectionFailure(this.location, cause);
         }
         try {
-            const [[edition, major, snapshot] = []] = await query(pool.request(), `SELECT CAST(SERVERPROPERTY('EngineEdition') AS int), CAST(SERVERPROPERTY('ProductMajorVersion') AS int), CAST(snapshot_isolation_state AS int) FROM sys.databases WHERE database_id = DB_ID()`);
+            const [[edition, major, snapshot] = []] = await query(pool.request(), this.location, `SELECT CAST(SERVERPROPERTY('EngineEdition') AS int), CAST(SERVERPROPERTY('ProductMajorVersion') AS int), CAST(snapshot_isolation_state AS int) FROM sys.databases WHERE database_id = DB_ID()`);
             const version = cellNumber(major, 'ProductMajorVersion');
             // Azure SQL Database (5) and Managed Instance (8) report version 12
             // but run the current engine.
@@ -51,15 +54,20 @@ export class SqlServerDatabase {
         }
     }
 }
-// Whether the server answered and refused the login. tedious marks the login
-// errors SQL Server raises while it fails over or is busy (4060, 10928,
-// 10929, 40197, 40501, 40613) as transient, and tries them again before it
-// gives up; those mean the server cannot be reached now.
-function refused(error) {
-    if (!(error instanceof sql.ConnectionError) || error.code !== 'ELOGIN')
-        return false;
-    const { originalError } = error;
-    return !(originalError !== undefined &&
-        'isTransient' in originalError &&
-        originalError.isTransient === true);
+// The login errors SQL Server raises while it fails over or is busy.
+const busyLoginErrors = new Set([4060, 10928, 10929, 40197, 40501, 40613]);
+// Marks a failed login as transient when the server raised one of those errors
+// on the way. tedious keeps only the last error of a login, and SQL Server
+// follows 4060 with 18456, which alone means a refused login. tedious also
+// leaves its own mark off the error of its last retry, so a database that stays
+// unavailable through its retries would read as refused.
+function markBusyLogin(connection) {
+    let busy = false;
+    connection.on('errorMessage', ({ number }) => {
+        busy ||= busyLoginErrors.has(number);
+    });
+    connection.once('connect', (error) => {
+        if (error !== undefined && busy)
+            error.isTransient = true;
+    });
 }

package/dist/sql-server-request.d.ts

@@ -1,3 +1,11 @@
 import sql from 'mssql';
-export declare function query(request: sql.Request, text: string, parameters?: readonly string[]): Promise<unknown[][]>;
-export declare function stream(request: sql.Request, text: string, parameters?: readonly string[]): AsyncGenerator<unknown[]>;
+export type SqlServerRead = {
+    readonly clock: {
+        setTimeout(callback: () => void, ms: number): unknown;
+        clearTimeout(timer: unknown): void;
+    };
+    readonly signal: AbortSignal | undefined;
+};
+export declare function connectionFailure(location: string, cause: unknown): Error;
+export declare function query(request: sql.Request, location: string, text: string, parameters?: readonly string[]): Promise<unknown[][]>;
+export declare function stream(request: sql.Request, text: string, parameters: readonly string[], { clock, signal }: SqlServerRead, location: string): AsyncGenerator<unknown[]>;

package/dist/sql-server-request.js

@@ -1,5 +1,12 @@
 import sql from 'mssql';
-import { SqlServerPermissionError } from './errors.js';
+import { SqlServerLoginError, SqlServerPermissionError, SqlServerUnavailableError, } from './errors.js';
+// How often a read checks that rows still arrive. A read that got no row from
+// one check to the next fails, so a server or network that stopped
+// sending fails it within two hours, the limit of Airbyte's source-mssql
+// (maxSecondsBetweenMessages: 7200 in its metadata.yaml). The driver has no such
+// limit: its request timeout stops at the first data, and a read of a whole
+// table can take any length of time.
+const silenceCheckMs = 3_600_000;
 // Every parameter travels as text and the statement casts it, so a value
 // keeps the exact spelling a read gave it, whatever the driver would make of
 // a number or a Date.
@@ -7,8 +14,35 @@ function bind(request, parameters) {
     for (const [index, value] of parameters.entries())
         request.input(`p${index}`, sql.NVarChar(sql.MAX), value);
 }
-// A refused read names the grant it needs (errors 229 and 230).
-function readError(error) {
+// What a failed connection means, when the pool opened it or a statement lost
+// it: a login the server refused is the user's to fix, and anything else can
+// succeed at a later attempt.
+export function connectionFailure(location, cause) {
+    return refused(cause)
+        ? new SqlServerLoginError(location, cause)
+        : new SqlServerUnavailableError(location, cause);
+}
+// Whether the server answered and refused the login. Its errors while it fails
+// over or is busy are marked as transient when the connection opens
+// (SqlServerDatabase); those mean the server cannot be reached now.
+function refused(error) {
+    if (!(error instanceof sql.ConnectionError) || error.code !== 'ELOGIN')
+        return false;
+    const { originalError } = error;
+    return !(originalError !== undefined &&
+        'isTransient' in originalError &&
+        originalError.isTransient === true);
+}
+// A failed statement as what it means. The connection failed under it when
+// the error has no server number, such as ECONNRESET, or when the server ended
+// the session: SQL Server ends the connection at severity 20 and above, as
+// error 596 does for a session that was killed. A refused read names the grant
+// it needs (errors 229 and 230).
+function readError(error, location) {
+    if (error instanceof sql.ConnectionError ||
+        (error instanceof sql.RequestError &&
+            (typeof error.number !== 'number' || Number(error.class) >= 20)))
+        return connectionFailure(location, error);
     if (!(error instanceof sql.RequestError))
         return error;
     if (error.number !== 229 && error.number !== 230)
@@ -26,7 +60,7 @@ function asRow(row) {
     return row;
 }
 // Every row of one statement, each as the values it selects in order.
-export async function query(request, text, parameters = []) {
+export async function query(request, location, text, parameters = []) {
     request.arrayRowMode = true;
     bind(request, parameters);
     try {
@@ -34,12 +68,14 @@ export async function query(request, text, parameters = []) {
         return recordset.map(asRow);
     }
     catch (error) {
-        throw readError(error);
+        throw readError(error, location);
     }
 }
 // The rows of one statement as the driver receives them; stopping early
-// cancels the statement so its connection returns to the pool.
-export async function* stream(request, text, parameters = []) {
+// cancels the statement so its connection returns to the pool. The signal stops
+// the read also while the driver has no row to give.
+export async function* stream(request, text, parameters, { clock, signal }, location) {
+    signal?.throwIfAborted();
     request.arrayRowMode = true;
     bind(request, parameters);
     const rows = request.toReadableStream();
@@ -49,17 +85,32 @@ export async function* stream(request, text, parameters = []) {
     void ended.then(() => {
         finished = true;
     });
+    let arrived = false;
+    const check = () => {
+        if (arrived) {
+            arrived = false;
+            timer = clock.setTimeout(check, silenceCheckMs);
+        }
+        else
+            rows.destroy(new SqlServerUnavailableError(location, new Error(`The server sent no row for over ${silenceCheckMs} ms`)));
+    };
+    let timer = clock.setTimeout(check, silenceCheckMs);
+    const stop = () => rows.destroy(signal?.reason);
+    signal?.addEventListener('abort', stop, { once: true });
     // In stream mode the promise always resolves; failures arrive on rows.
     void request.query(text);
     try {
         for await (const row of rows) {
+            arrived = true;
             yield asRow(row);
         }
     }
     catch (error) {
-        throw readError(error);
+        throw readError(error, location);
     }
     finally {
+        clock.clearTimeout(timer);
+        signal?.removeEventListener('abort', stop);
         // A reader that stops early cancels the statement, and waits for it to
         // end: until then the connection, or a transaction on it, is not free.
         if (!finished) {

package/dist/sql-server-session.d.ts

@@ -1,5 +1,6 @@
 import sql from 'mssql';
 import { type ChangePosition, ChangeSet } from './change-set.ts';
+import { type SqlServerRead } from './sql-server-request.ts';
 import { SqlServerRow } from './sql-server-row.ts';
 import { SqlServerTable } from './sql-server-table.ts';
 export type SqlServerVersion = {
@@ -17,8 +18,8 @@ export declare class SqlServerSession implements AsyncDisposable {
     lastWrites(): Promise<ReadonlyMap<string, string>>;
     changeTrackingPosition(table: SqlServerTable): Promise<ChangePosition>;
     minActiveRowversion(): Promise<string>;
-    page(table: SqlServerTable, after: readonly string[] | null, limit: number): AsyncGenerator<SqlServerRow>;
-    rowversions(table: SqlServerTable, above: string, below: string, limit: number): AsyncGenerator<SqlServerRow>;
-    rows(table: SqlServerTable): AsyncGenerator<SqlServerRow>;
-    changes(table: SqlServerTable, since: ChangePosition): Promise<ChangeSet>;
+    page(table: SqlServerTable, after: readonly string[] | null, limit: number, read: SqlServerRead): AsyncGenerator<SqlServerRow>;
+    rowversions(table: SqlServerTable, above: string, below: string, limit: number, read: SqlServerRead): AsyncGenerator<SqlServerRow>;
+    rows(table: SqlServerTable, read: SqlServerRead): AsyncGenerator<SqlServerRow>;
+    changes(table: SqlServerTable, since: ChangePosition, read: SqlServerRead): Promise<ChangeSet>;
 }

package/dist/sql-server-session.js

@@ -104,9 +104,9 @@ export class SqlServerSession {
     // login can read.
     async tables() {
         const [tables, columns, keys] = await Promise.all([
-            query(this.#pool.request(), tablesQuery),
-            query(this.#pool.request(), columnsQuery),
-            query(this.#pool.request(), primaryKeysQuery),
+            query(this.#pool.request(), this.#location, tablesQuery),
+            query(this.#pool.request(), this.#location, columnsQuery),
+            query(this.#pool.request(), this.#location, primaryKeysQuery),
         ]);
         const columnsOf = groupBy(columns);
         const keysOf = groupBy(keys);
@@ -152,7 +152,7 @@ export class SqlServerSession {
         });
     }
     async version() {
-        const [[changeTracking, rowversion] = []] = await query(this.#pool.request(), 'SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), CONVERT(varchar(20), CAST(@@DBTS AS bigint))');
+        const [[changeTracking, rowversion] = []] = await query(this.#pool.request(), this.#location, 'SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), CONVERT(varchar(20), CAST(@@DBTS AS bigint))');
         return Object.freeze({
             changeTracking: cellNullableText(changeTracking, 'change tracking version'),
             rowversion: cellText(rowversion, '@@DBTS'),
@@ -165,7 +165,7 @@ export class SqlServerSession {
     // statistics has no count, so its value never moves. A login that can read
     // a table can read its counts.
     async statistics() {
-        const rows = await query(this.#pool.request(), statisticsQuery);
+        const rows = await query(this.#pool.request(), this.#location, statisticsQuery);
         return new Map(rows.map(([table, counts]) => [
             cellText(table, 'table'),
             cellText(counts, 'statistics'),
@@ -176,7 +176,7 @@ export class SqlServerSession {
     // also in a table whose statistics SQL Server has not built, but an update
     // does not. A login that can read a table can read its count.
     async rowCounts() {
-        const rows = await query(this.#pool.request(), rowCountsQuery);
+        const rows = await query(this.#pool.request(), this.#location, rowCountsQuery);
         return new Map(rows.map(([table, count]) => [
             cellText(table, 'table'),
             cellText(count, 'row count'),
@@ -188,7 +188,7 @@ export class SqlServerSession {
     // so the value of each table is then empty. A login needs VIEW SERVER
     // STATE to read them (VIEW DATABASE STATE on Azure SQL Database).
     async lastWrites() {
-        const rows = await query(this.#pool.request(), lastWritesQuery).catch((error) => {
+        const rows = await query(this.#pool.request(), this.#location, lastWritesQuery).catch((error) => {
             // 297: the login may not read the state of the server or database.
             if (error instanceof sql.RequestError && error.number === 297)
                 throw new SqlServerPermissionError('VIEW SERVER STATE (VIEW DATABASE STATE on Azure SQL Database)', error);
@@ -203,7 +203,7 @@ export class SqlServerSession {
     // before the rows, so a change made during the read is read again, never
     // missed.
     async changeTrackingPosition(table) {
-        const [[version, generation] = []] = await query(this.#pool.request(), `SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), ${generationQuery}`, [table.quoted]);
+        const [[version, generation] = []] = await query(this.#pool.request(), this.#location, `SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), ${generationQuery}`, [table.quoted]);
         if (version === null || generation === null)
             throw new TypeError(`Change Tracking is off for ${table.quoted} in ${this.#location}`);
         return Object.freeze({
@@ -214,13 +214,13 @@ export class SqlServerSession {
     // Rows below this rowversion are committed; one at or above it may belong
     // to a transaction still open, so a read stops short of it.
     async minActiveRowversion() {
-        const [[value] = []] = await query(this.#pool.request(), 'SELECT CONVERT(varchar(20), CAST(MIN_ACTIVE_ROWVERSION() AS bigint))');
+        const [[value] = []] = await query(this.#pool.request(), this.#location, 'SELECT CONVERT(varchar(20), CAST(MIN_ACTIVE_ROWVERSION() AS bigint))');
         return cellText(value, 'MIN_ACTIVE_ROWVERSION');
     }
     // Up to limit rows in primary key order, after the given position. The
     // whole key compares as a tuple, each part cast to its column's type, so
     // pages neither skip nor repeat rows that share a leading key value.
-    async *page(table, after, limit) {
+    async *page(table, after, limit, read) {
         if (!table.pageable)
             throw new TypeError(`${table.quoted} has no primary key a read can page by`);
         const keys = table.primaryKey;
@@ -236,20 +236,20 @@ export class SqlServerSession {
                 `${key(index)} > ${cast(index)}`,
             ].join(' AND ')})`)
                 .join(' OR ')}`;
-        yield* this.#rows(table, `SELECT TOP (${count(limit)}) ${selection(table)} FROM ${table.quoted} AS t ${where} ORDER BY ${keys.map((_, index) => key(index)).join(', ')}`, after ?? []);
+        yield* this.#rows(table, `SELECT TOP (${count(limit)}) ${selection(table)} FROM ${table.quoted} AS t ${where} ORDER BY ${keys.map((_, index) => key(index)).join(', ')}`, after ?? [], read);
     }
     // Up to limit rows whose rowversion is above `above` and below `below`, in
     // rowversion order.
-    async *rowversions(table, above, below, limit) {
+    async *rowversions(table, above, below, limit, read) {
         const column = table.rowversion;
         if (column === undefined)
             throw new TypeError(`${table.quoted} has no rowversion column`);
         const version = `t.${column.quoted}`;
-        yield* this.#rows(table, `SELECT TOP (${count(limit)}) ${selection(table)} FROM ${table.quoted} AS t WHERE ${version} > ${column.codec.cast('@p0')} AND ${version} < ${column.codec.cast('@p1')} ORDER BY ${version}`, [above, below]);
+        yield* this.#rows(table, `SELECT TOP (${count(limit)}) ${selection(table)} FROM ${table.quoted} AS t WHERE ${version} > ${column.codec.cast('@p0')} AND ${version} < ${column.codec.cast('@p1')} ORDER BY ${version}`, [above, below], read);
     }
     // Every row, in no particular order.
-    async *rows(table) {
-        yield* this.#rows(table, `SELECT ${selection(table)} FROM ${table.quoted} AS t`, []);
+    async *rows(table, read) {
+        yield* this.#rows(table, `SELECT ${selection(table)} FROM ${table.quoted} AS t`, [], read);
     }
     // What changed in the table since a position in its change history: each
     // changed key once, with its row as it is now, or as a deletion. A position
@@ -259,7 +259,8 @@ export class SqlServerSession {
     // first, so a change made during the read is read again next time, and the
     // check runs again after the read in case cleanup removed history
     // meanwhile.
-    async changes(table, since) {
+    async changes(table, since, read) {
+        const location = this.#location;
         if (table.primaryKey.length === 0)
             throw new TypeError(`${table.quoted} has no primary key to track changes by`);
         const transaction = this.#snapshot
@@ -277,7 +278,7 @@ export class SqlServerSession {
             ? this.#pool.request()
             : new sql.Request(transaction);
         const check = async () => {
-            const [[current, minimum, viewable, generation, begin] = []] = await query(request(), `SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), CONVERT(varchar(20), CHANGE_TRACKING_MIN_VALID_VERSION(OBJECT_ID(@p0))), HAS_PERMS_BY_NAME(@p0, 'OBJECT', 'VIEW CHANGE TRACKING'), ${generationQuery}, (SELECT CONVERT(varchar(20), begin_version) FROM sys.change_tracking_tables WHERE object_id = OBJECT_ID(@p0))`, [table.quoted]);
+            const [[current, minimum, viewable, generation, begin] = []] = await query(request(), location, `SELECT CONVERT(varchar(20), CHANGE_TRACKING_CURRENT_VERSION()), CONVERT(varchar(20), CHANGE_TRACKING_MIN_VALID_VERSION(OBJECT_ID(@p0))), HAS_PERMS_BY_NAME(@p0, 'OBJECT', 'VIEW CHANGE TRACKING'), ${generationQuery}, (SELECT CONVERT(varchar(20), begin_version) FROM sys.change_tracking_tables WHERE object_id = OBJECT_ID(@p0))`, [table.quoted]);
             // Without the grant SQL Server still reports a minimum valid version
             // (0), so the grant itself is checked first.
             if (viewable !== 1)
@@ -306,7 +307,7 @@ SELECT ${present}, ${changed.join(', ')}, ${selection(table)}
 FROM CHANGETABLE(CHANGES ${table.quoted}, @since) AS ct
 LEFT JOIN ${table.quoted} AS t ON ${keys.map((column) => `t.${column.quoted} = ct.${column.quoted}`).join(' AND ')}`;
             const changes = async function* () {
-                for await (const values of stream(request(), text, [since.version])) {
+                for await (const values of stream(request(), text, [since.version], read, location)) {
                     const [exists] = values;
                     const key = decode(keys, values.slice(1, 1 + changed.length));
                     yield exists === 1
@@ -331,8 +332,8 @@ LEFT JOIN ${table.quoted} AS t ON ${keys.map((column) => `t.${column.quoted} = c
             throw error;
         }
     }
-    async *#rows(table, text, parameters) {
-        for await (const values of stream(this.#pool.request(), text, parameters))
+    async *#rows(table, text, parameters, read) {
+        for await (const values of stream(this.#pool.request(), text, parameters, read, this.#location))
             yield new SqlServerRow(table, decode(table.columns, values));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eltjs/sdk-microsoft-sql-server",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Reads one SQL Server database: discovery, exact reads, Change Tracking and change signals. It knows nothing of elt.",
   "license": "Apache-2.0",
   "repository": {