dbtour-source-mssql 0.7.1 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,12 @@
-import type { Database, SourceConfig } from 'dbtour';
-export { mapRecordsets, toRecordsets, formatType } from './map.ts';
+import { type Database, type QueryResult, type RunOptions, type SourceConfig } from 'dbtour';
+export { mapRecordsets, RowCollector, sizeOf, toRecordsets, formatType } from './map.ts';
 export declare const query: string;
 export declare function extract(config: SourceConfig): Promise<Database>;
+/**
+ * Runs one query dbtour has checked, with `connection` already the source's reader, a read-only login. It runs
+ * inside a transaction that is always rolled back, so nothing it did is kept even if the login could write. Its
+ * rows stream into a collector that stops at the limit or the byte budget, whichever comes first, and the query
+ * is cancelled there, so neither the rows nor their size is ever more than a row past what is kept; SET ROWCOUNT
+ * stops the server one row past the limit too. A timer cancels it at the timeout.
+ */
+export declare function run(config: SourceConfig, text: string, options: RunOptions): Promise<QueryResult>;

package/dist/index.js

@@ -3,8 +3,9 @@
 // mssql:// URL. It is read from the environment variable dbtour.yaml names, never from the file.
 import { readFileSync } from 'node:fs';
 import sql from 'mssql';
-import { mapRecordsets, toRecordsets } from "./map.js";
-export { mapRecordsets, toRecordsets, formatType } from "./map.js";
+import { maxResultBytes } from 'dbtour';
+import { mapRecordsets, RowCollector, toRecordsets } from "./map.js";
+export { mapRecordsets, RowCollector, sizeOf, toRecordsets, formatType } from "./map.js";
 export const query = readFileSync(new URL('./query.sql', import.meta.url), 'utf8');
 export async function extract(config) {
     if (!config.connection) {
@@ -21,3 +22,77 @@ export async function extract(config) {
         await pool.close();
     }
 }
+/**
+ * Some seconds past dbtour's own timeout for the driver's: the driver's default (15 seconds) would otherwise end
+ * a query first, with a message that says nothing of what to do, so dbtour's cancel always comes first.
+ */
+const driverGraceMs = 5000;
+/**
+ * Runs one query dbtour has checked, with `connection` already the source's reader, a read-only login. It runs
+ * inside a transaction that is always rolled back, so nothing it did is kept even if the login could write. Its
+ * rows stream into a collector that stops at the limit or the byte budget, whichever comes first, and the query
+ * is cancelled there, so neither the rows nor their size is ever more than a row past what is kept; SET ROWCOUNT
+ * stops the server one row past the limit too. A timer cancels it at the timeout.
+ */
+export async function run(config, text, options) {
+    if (!config.connection)
+        throw new Error(`Source ${config.name} has no reader connection: add "reader: \${DBTOUR_MSSQL_READER}" to it in dbtour.yaml and set that variable`);
+    const pool = new sql.ConnectionPool(config.connection);
+    await pool.connect();
+    // The driver takes a per-transaction timeout, cascaded to its requests; its type definitions predate that.
+    const begin = pool.transaction;
+    const transaction = begin.call(pool, { requestTimeout: options.timeoutMs + driverGraceMs });
+    const rows = new RowCollector(options.limit, maxResultBytes);
+    let timedOut = false;
+    try {
+        await transaction.begin();
+        const request = transaction.request();
+        // Rows as arrays, so two columns with the same name both come back; streamed, so they are counted as they come.
+        request.arrayRowMode = true;
+        request.stream = true;
+        let cancelling = false;
+        const cancel = () => {
+            if (!cancelling) {
+                cancelling = true;
+                request.cancel();
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            cancel();
+        }, options.timeoutMs);
+        try {
+            await new Promise((done, fail) => {
+                request.on('recordset', (columns) => rows.start(columns));
+                request.on('row', (row) => {
+                    if (!rows.add(row))
+                        cancel();
+                });
+                // A cancel ends in an error the driver raises; it is only a failure when dbtour did not ask for it. The
+                // error comes before the request has finished, and a rollback asked for then is refused and the connection
+                // stays held, so pool.close() would wait for ever: the first error is kept, and given once 'done' follows.
+                let failure;
+                request.on('error', (error) => {
+                    if (!cancelling)
+                        failure ??= error;
+                });
+                request.on('done', () => (failure ? fail(failure) : done()));
+                // The semicolon before the query lets it start with WITH, which T-SQL wants after a statement.
+                void request.query(`SET ROWCOUNT ${options.limit + 1};\n${text};\nSET ROWCOUNT 0;`);
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (timedOut) {
+            const seconds = options.timeoutMs / 1000;
+            throw new Error(`The query ran past ${seconds} ${seconds === 1 ? 'second' : 'seconds'} and was cancelled: narrow it with a filter on an indexed column, or TOP`);
+        }
+        return rows.result();
+    }
+    finally {
+        // Always rolled back: a read keeps nothing, and a write that got past every other guard is undone.
+        await transaction.rollback().catch(() => undefined);
+        await pool.close();
+    }
+}

package/dist/map.d.ts

@@ -1,4 +1,4 @@
-import type { Database } from 'dbtour';
+import type { Database, QueryResult } from 'dbtour';
 /** node-mssql returns a bigint as a string, since it may not fit a JavaScript number. */
 type Count = number | string;
 /** Whether the sensitivity labels were read: the view is absent before SQL Server 2019, or the login may not. */
@@ -177,4 +177,28 @@ export declare function toRecordsets(sets: unknown[][]): Recordsets;
 export declare function mapRecordsets(sets: Recordsets, options?: MapOptions): Database;
 /** The type as SQL Server would spell it in a CREATE TABLE: nvarchar(320), varchar(max), decimal(18,2), datetime2(7). */
 export declare function formatType(row: Pick<ColumnRow, 'type' | 'maxLength' | 'precision' | 'scale'>): string;
+/** Roughly how many bytes a value holds in memory: text two to a character, bytes as they are. */
+export declare function sizeOf(value: unknown): number;
+/**
+ * The rows of a query as they stream in, kept until one is past the limit or they outgrow the byte budget.
+ * add() says whether to go on; run() cancels the query when it says no, so neither the rows nor their size
+ * is ever more than one row past what is kept.
+ */
+export declare class RowCollector {
+    private columns;
+    private rows;
+    private bytes;
+    private stopped?;
+    private readonly limit;
+    private readonly budget;
+    constructor(limit: number, budget: number);
+    /** A new result set: its columns, and its rows from nothing. */
+    start(columns: {
+        name: string;
+    }[]): void;
+    add(row: unknown[]): boolean;
+    /** Whether add() has stopped it; a cancelled query's error is then expected, not a failure. */
+    get done(): boolean;
+    result(): QueryResult;
+}
 export {};

package/dist/map.js

@@ -286,3 +286,60 @@ function groupBy(rows, key) {
 function pattern(text) {
     return new RegExp('^' + text.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i');
 }
+/** Roughly how many bytes a value holds in memory: text two to a character, bytes as they are. */
+export function sizeOf(value) {
+    if (value === null || value === undefined)
+        return 1;
+    if (typeof value === 'string')
+        return value.length * 2;
+    if (value instanceof Uint8Array)
+        return value.length;
+    return 8;
+}
+/**
+ * The rows of a query as they stream in, kept until one is past the limit or they outgrow the byte budget.
+ * add() says whether to go on; run() cancels the query when it says no, so neither the rows nor their size
+ * is ever more than one row past what is kept.
+ */
+export class RowCollector {
+    columns = [];
+    rows = [];
+    bytes = 0;
+    stopped;
+    limit;
+    budget;
+    constructor(limit, budget) {
+        this.limit = limit;
+        this.budget = budget;
+    }
+    /** A new result set: its columns, and its rows from nothing. */
+    start(columns) {
+        this.columns = columns.map((c, i) => c.name || `(column ${i + 1})`);
+        this.rows = [];
+        this.bytes = 0;
+    }
+    add(row) {
+        if (this.rows.length >= this.limit) {
+            this.stopped = 'limit';
+            return false;
+        }
+        const size = row.reduce((sum, value) => sum + sizeOf(value), 0);
+        if (this.bytes + size > this.budget) {
+            this.stopped = 'size';
+            return false;
+        }
+        this.rows.push(row);
+        this.bytes += size;
+        return true;
+    }
+    /** Whether add() has stopped it; a cancelled query's error is then expected, not a failure. */
+    get done() {
+        return this.stopped !== undefined;
+    }
+    result() {
+        const result = { columns: this.columns, rows: this.rows, truncated: this.stopped !== undefined, limit: this.limit };
+        if (this.stopped)
+            result.reason = this.stopped;
+        return result;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour-source-mssql",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "SQL Server source for dbtour: tables, views, columns, keys, relations, indexes, descriptions.",
   "type": "module",
   "license": "MIT",
@@ -36,6 +36,6 @@
   },
   "devDependencies": {
     "@types/mssql": "^9.1.8",
-    "dbtour": "0.7.1"
+    "dbtour": "0.9.0"
   }
 }