dbtour-source-mssql 0.0.0-stage → 0.2.4

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Database, SourceConfig } from 'dbtour';
+export { mapRecordsets, toRecordsets, formatType } from './map.ts';
+export declare const query: string;
+export declare function extract(config: SourceConfig): Promise<Database>;

package/dist/index.js

@@ -0,0 +1,23 @@
+// The SQL Server source. `connection` is anything the mssql package accepts: an ADO string
+// (Server=host,1433;Database=Shop;User Id=reader;Password=…;TrustServerCertificate=True) or an
+// 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";
+export const query = readFileSync(new URL('./query.sql', import.meta.url), 'utf8');
+export async function extract(config) {
+    if (!config.connection) {
+        throw new Error(`Source ${config.name} has no connection: add "connection: \${DBTOUR_MSSQL}" to it in dbtour.yaml and set that variable`);
+    }
+    const pool = new sql.ConnectionPool(config.connection);
+    await pool.connect();
+    try {
+        const result = await pool.request().query(query);
+        const exclude = Array.isArray(config.exclude) ? config.exclude.map(String) : undefined;
+        return mapRecordsets(toRecordsets(result.recordsets), { name: config.name, exclude });
+    }
+    finally {
+        await pool.close();
+    }
+}

package/dist/map.d.ts

@@ -0,0 +1,85 @@
+import type { Database } from 'dbtour';
+export interface InfoRow {
+    name: string;
+    version: string | null;
+    description: string | null;
+}
+export interface TableRow {
+    schema: string;
+    name: string;
+    kind: 'table' | 'view';
+    description: string | null;
+    definition: string | null;
+}
+export interface ColumnRow {
+    schema: string;
+    table: string;
+    name: string;
+    position: number;
+    type: string;
+    maxLength: number;
+    precision: number;
+    scale: number;
+    nullable: boolean;
+    identity: boolean;
+    default: string | null;
+    computed: string | null;
+    description: string | null;
+}
+export interface KeyRow {
+    schema: string;
+    table: string;
+    name: string;
+    kind: 'PK' | 'UQ';
+    column: string;
+    ordinal: number;
+}
+export interface ForeignKeyRow {
+    name: string;
+    schema: string;
+    table: string;
+    column: string;
+    toSchema: string;
+    toTable: string;
+    toColumn: string;
+    ordinal: number;
+    onDelete: string;
+    onUpdate: string;
+}
+export interface IndexRow {
+    schema: string;
+    table: string;
+    name: string;
+    unique: boolean;
+    primary: boolean;
+    column: string;
+    ordinal: number;
+    included: boolean;
+}
+export interface CheckRow {
+    schema: string;
+    table: string;
+    name: string;
+    definition: string;
+    column: string | null;
+}
+export interface Recordsets {
+    info: InfoRow[];
+    tables: TableRow[];
+    columns: ColumnRow[];
+    keys: KeyRow[];
+    foreignKeys: ForeignKeyRow[];
+    indexes: IndexRow[];
+    checks: CheckRow[];
+}
+export interface MapOptions {
+    /** The name the docs call the database; the server's own name when not given. */
+    name?: string;
+    /** Tables to leave out, as schema.table with * for any run of characters: `dbo.sys*`, `*.webpages_*`. */
+    exclude?: string[];
+}
+/** The result sets in the order query.sql returns them. */
+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;

package/dist/map.js

@@ -0,0 +1,134 @@
+/** The result sets in the order query.sql returns them. */
+export function toRecordsets(sets) {
+    if (sets.length !== 7)
+        throw new Error(`query.sql returns 7 result sets, got ${sets.length}: the query and map.ts disagree`);
+    const [info, tables, columns, keys, foreignKeys, indexes, checks] = sets;
+    return { info, tables, columns, keys, foreignKeys, indexes, checks };
+}
+export function mapRecordsets(sets, options = {}) {
+    const info = sets.info[0];
+    const excluded = (options.exclude ?? []).map(pattern);
+    const keep = (schema, table) => !excluded.some((p) => p.test(`${schema}.${table}`));
+    const tables = new Map();
+    const schemas = [];
+    for (const row of sets.tables) {
+        if (!keep(row.schema, row.name))
+            continue;
+        let schema = schemas.find((s) => s.name === row.schema);
+        if (!schema)
+            schemas.push((schema = { name: row.schema, tables: [] }));
+        const table = { name: row.name, kind: row.kind, columns: [], indexes: [], constraints: [] };
+        if (row.description)
+            table.description = row.description;
+        if (row.kind === 'view' && row.definition)
+            table.definition = row.definition;
+        schema.tables.push(table);
+        tables.set(`${row.schema}.${row.name}`, table);
+    }
+    for (const row of sets.columns) {
+        const table = tables.get(`${row.schema}.${row.table}`);
+        if (!table)
+            continue;
+        const column = { name: row.name, type: formatType(row), nullable: Boolean(row.nullable) };
+        if (row.default !== null)
+            column.default = row.default;
+        if (row.computed !== null)
+            column.computed = row.computed;
+        if (row.identity)
+            column.identity = true;
+        if (row.description)
+            column.description = row.description;
+        table.columns.push(column);
+    }
+    for (const [key, rows] of groupBy(sets.keys, (r) => `${r.schema}.${r.table}|${r.name}`)) {
+        const table = tables.get(key.split('|')[0]);
+        if (!table)
+            continue;
+        const columns = rows.sort((a, b) => a.ordinal - b.ordinal).map((r) => r.column);
+        if (rows[0].kind === 'PK')
+            table.primaryKey = columns;
+        table.constraints.push({ name: rows[0].name, kind: rows[0].kind === 'PK' ? 'primary' : 'unique', columns });
+    }
+    const relations = [];
+    for (const [, rows] of groupBy(sets.foreignKeys, (r) => r.name)) {
+        const ordered = rows.sort((a, b) => a.ordinal - b.ordinal);
+        const first = ordered[0];
+        const from = `${first.schema}.${first.table}`;
+        const to = `${first.toSchema}.${first.toTable}`;
+        if (!tables.has(from) || !tables.has(to))
+            continue;
+        const relation = { name: first.name, from: { table: from, columns: ordered.map((r) => r.column) }, to: { table: to, columns: ordered.map((r) => r.toColumn) } };
+        if (first.onDelete && first.onDelete !== 'NO_ACTION')
+            relation.onDelete = first.onDelete;
+        if (first.onUpdate && first.onUpdate !== 'NO_ACTION')
+            relation.onUpdate = first.onUpdate;
+        relations.push(relation);
+        tables.get(from).constraints.push({ name: first.name, kind: 'foreign', columns: relation.from.columns, definition: `${to} (${relation.to.columns.join(', ')})` });
+    }
+    for (const [key, rows] of groupBy(sets.indexes, (r) => `${r.schema}.${r.table}|${r.name}`)) {
+        const table = tables.get(key.split('|')[0]);
+        if (!table || rows[0].primary)
+            continue;
+        const index = {
+            name: rows[0].name,
+            columns: rows.filter((r) => !r.included).sort((a, b) => a.ordinal - b.ordinal).map((r) => r.column),
+            unique: Boolean(rows[0].unique),
+        };
+        const included = rows.filter((r) => r.included).map((r) => r.column);
+        if (included.length > 0)
+            index.included = included;
+        table.indexes.push(index);
+    }
+    for (const row of sets.checks) {
+        const table = tables.get(`${row.schema}.${row.table}`);
+        if (!table)
+            continue;
+        const constraint = { name: row.name, kind: 'check', columns: row.column ? [row.column] : [], definition: row.definition };
+        table.constraints.push(constraint);
+    }
+    const database = { name: options.name ?? info.name, driver: 'mssql', schemas, relations };
+    if (info.version)
+        database.version = info.version;
+    if (info.description)
+        database.description = info.description;
+    return database;
+}
+/** The type as SQL Server would spell it in a CREATE TABLE: nvarchar(320), varchar(max), decimal(18,2), datetime2(7). */
+export function formatType(row) {
+    const t = row.type.toLowerCase();
+    switch (t) {
+        case 'char':
+        case 'varchar':
+        case 'binary':
+        case 'varbinary':
+            return `${t}(${row.maxLength === -1 ? 'max' : row.maxLength})`;
+        case 'nchar':
+        case 'nvarchar':
+            // max_length counts bytes; these types hold two per character.
+            return `${t}(${row.maxLength === -1 ? 'max' : row.maxLength / 2})`;
+        case 'decimal':
+        case 'numeric':
+            return `${t}(${row.precision},${row.scale})`;
+        case 'datetime2':
+        case 'datetimeoffset':
+        case 'time':
+            return `${t}(${row.scale})`;
+        default:
+            return t;
+    }
+}
+function groupBy(rows, key) {
+    const groups = new Map();
+    for (const row of rows) {
+        const k = key(row);
+        const group = groups.get(k);
+        if (group)
+            group.push(row);
+        else
+            groups.set(k, [row]);
+    }
+    return groups;
+}
+function pattern(text) {
+    return new RegExp('^' + text.split('*').map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$', 'i');
+}

package/dist/query.sql

@@ -0,0 +1,108 @@
+-- Everything dbtour needs from SQL Server, in one batch of seven result sets, read in this order by map.ts.
+-- Reads the catalogue views only: a login with VIEW DEFINITION on the database is enough.
+SET NOCOUNT ON;
+
+-- 1. The database
+SELECT DB_NAME() AS [name],
+       CAST(SERVERPROPERTY('ProductVersion') AS nvarchar(50)) AS [version],
+       (SELECT TOP (1) CAST([value] AS nvarchar(max)) FROM sys.extended_properties WHERE class = 0 AND [name] = 'MS_Description') AS [description];
+
+-- 2. Tables and views
+SELECT s.[name] AS [schema],
+       o.[name] AS [name],
+       CASE o.[type] WHEN 'V' THEN 'view' ELSE 'table' END AS [kind],
+       CAST(ep.[value] AS nvarchar(max)) AS [description],
+       m.[definition] AS [definition]
+FROM sys.objects o
+JOIN sys.schemas s ON s.schema_id = o.schema_id
+LEFT JOIN sys.extended_properties ep ON ep.class = 1 AND ep.major_id = o.object_id AND ep.minor_id = 0 AND ep.[name] = 'MS_Description'
+LEFT JOIN sys.sql_modules m ON m.object_id = o.object_id
+WHERE o.[type] IN ('U', 'V') AND o.is_ms_shipped = 0
+ORDER BY s.[name], o.[name];
+
+-- 3. Columns
+SELECT s.[name] AS [schema],
+       o.[name] AS [table],
+       c.[name] AS [name],
+       c.column_id AS [position],
+       t.[name] AS [type],
+       c.max_length AS [maxLength],
+       c.[precision] AS [precision],
+       c.scale AS [scale],
+       c.is_nullable AS [nullable],
+       c.is_identity AS [identity],
+       d.[definition] AS [default],
+       cc.[definition] AS [computed],
+       CAST(ep.[value] AS nvarchar(max)) AS [description]
+FROM sys.columns c
+JOIN sys.objects o ON o.object_id = c.object_id AND o.[type] IN ('U', 'V') AND o.is_ms_shipped = 0
+JOIN sys.schemas s ON s.schema_id = o.schema_id
+JOIN sys.types t ON t.user_type_id = c.user_type_id
+LEFT JOIN sys.default_constraints d ON d.object_id = c.default_object_id
+LEFT JOIN sys.computed_columns cc ON cc.object_id = c.object_id AND cc.column_id = c.column_id
+LEFT JOIN sys.extended_properties ep ON ep.class = 1 AND ep.major_id = c.object_id AND ep.minor_id = c.column_id AND ep.[name] = 'MS_Description'
+ORDER BY s.[name], o.[name], c.column_id;
+
+-- 4. Primary keys and unique constraints, one row per column
+SELECT s.[name] AS [schema],
+       o.[name] AS [table],
+       kc.[name] AS [name],
+       kc.[type] AS [kind],
+       c.[name] AS [column],
+       ic.key_ordinal AS [ordinal]
+FROM sys.key_constraints kc
+JOIN sys.objects o ON o.object_id = kc.parent_object_id AND o.is_ms_shipped = 0
+JOIN sys.schemas s ON s.schema_id = o.schema_id
+JOIN sys.index_columns ic ON ic.object_id = kc.parent_object_id AND ic.index_id = kc.unique_index_id AND ic.key_ordinal > 0
+JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+ORDER BY s.[name], o.[name], kc.[name], ic.key_ordinal;
+
+-- 5. Foreign keys, one row per column pair
+SELECT fk.[name] AS [name],
+       ps.[name] AS [schema],
+       po.[name] AS [table],
+       pc.[name] AS [column],
+       rs.[name] AS [toSchema],
+       ro.[name] AS [toTable],
+       rc.[name] AS [toColumn],
+       fkc.constraint_column_id AS [ordinal],
+       fk.delete_referential_action_desc AS [onDelete],
+       fk.update_referential_action_desc AS [onUpdate]
+FROM sys.foreign_keys fk
+JOIN sys.foreign_key_columns fkc ON fkc.constraint_object_id = fk.object_id
+JOIN sys.objects po ON po.object_id = fk.parent_object_id
+JOIN sys.schemas ps ON ps.schema_id = po.schema_id
+JOIN sys.columns pc ON pc.object_id = fkc.parent_object_id AND pc.column_id = fkc.parent_column_id
+JOIN sys.objects ro ON ro.object_id = fk.referenced_object_id
+JOIN sys.schemas rs ON rs.schema_id = ro.schema_id
+JOIN sys.columns rc ON rc.object_id = fkc.referenced_object_id AND rc.column_id = fkc.referenced_column_id
+ORDER BY fk.[name], fkc.constraint_column_id;
+
+-- 6. Indexes, one row per column, key columns then included ones
+SELECT s.[name] AS [schema],
+       o.[name] AS [table],
+       i.[name] AS [name],
+       i.is_unique AS [unique],
+       i.is_primary_key AS [primary],
+       c.[name] AS [column],
+       ic.key_ordinal AS [ordinal],
+       ic.is_included_column AS [included]
+FROM sys.indexes i
+JOIN sys.objects o ON o.object_id = i.object_id AND o.[type] IN ('U', 'V') AND o.is_ms_shipped = 0
+JOIN sys.schemas s ON s.schema_id = o.schema_id
+JOIN sys.index_columns ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
+JOIN sys.columns c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
+WHERE i.[name] IS NOT NULL AND i.[type] > 0
+ORDER BY s.[name], o.[name], i.[name], ic.is_included_column, ic.key_ordinal, ic.index_column_id;
+
+-- 7. Check constraints
+SELECT s.[name] AS [schema],
+       o.[name] AS [table],
+       ck.[name] AS [name],
+       ck.[definition] AS [definition],
+       c.[name] AS [column]
+FROM sys.check_constraints ck
+JOIN sys.objects o ON o.object_id = ck.parent_object_id AND o.is_ms_shipped = 0
+JOIN sys.schemas s ON s.schema_id = o.schema_id
+LEFT JOIN sys.columns c ON c.object_id = ck.parent_object_id AND c.column_id = ck.parent_column_id
+ORDER BY s.[name], o.[name], ck.[name];

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "dbtour-source-mssql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.4",
+  "description": "SQL Server source for dbtour: tables, views, columns, keys, relations, indexes, descriptions.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Victor Saly",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/victorsaly/dbtour.git",
+    "directory": "packages/source-mssql"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "node ../../scripts/build.mjs"
+  },
+  "keywords": [
+    "dbtour",
+    "mssql",
+    "sql-server",
+    "schema"
+  ],
+  "dependencies": {
+    "mssql": "^12.7.13"
+  },
+  "devDependencies": {
+    "@types/mssql": "^9.1.8",
+    "dbtour": "0.2.4"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.