dbtour 0.3.0 → 0.4.0

package/dist/cli.js

@@ -89,6 +89,9 @@ async function extract(io) {
             model.databases.push(result);
             const tables = result.schemas.reduce((n, s) => n + s.tables.length, 0);
             io.log(`${result.name}: ${tables} tables, ${result.relations.length} relations`);
+            // Not a failure: the rest was read, and an absence the model records is not taken for a no.
+            for (const reason of result.unread ?? [])
+                io.log(`${result.name}: not read: ${reason}. Grant it to read them, or leave them out.`);
         }
         else {
             model.apis.push(result);

package/dist/model.d.ts

@@ -1,4 +1,15 @@
 export declare const MODEL_VERSION = 1;
+/**
+ * Extended properties other than MS_Description (which is `description`), by name: what a team records about
+ * an object in the database itself, such as its owner, source or retention.
+ */
+export type Properties = Record<string, string>;
+/** A column's sensitivity classification, as SQL Server's data discovery or a team set it. */
+export interface Sensitivity {
+    label?: string;
+    informationType?: string;
+    rank?: string;
+}
 export interface Column {
     name: string;
     /** As the database spells it, with its size: nvarchar(320), decimal(18,2). */
@@ -8,19 +19,62 @@ export interface Column {
     /** The expression of a computed column. */
     computed?: string;
     identity?: boolean;
+    /** An identity's seed and increment, as the database spells them. */
+    identitySeed?: string;
+    identityIncrement?: string;
     description?: string;
+    /** Only where it differs from the database's collation. */
+    collation?: string;
+    sparse?: boolean;
+    /** The dynamic data masking function: default(), email(), partial(2,"XX",0). */
+    masked?: string;
+    /** Always Encrypted: how, and under which column encryption key. */
+    encrypted?: {
+        type: 'deterministic' | 'randomized';
+        key: string;
+    };
+    sensitivity?: Sensitivity;
+    properties?: Properties;
 }
 export interface Index {
     name: string;
     columns: string[];
     unique: boolean;
     included?: string[];
+    /** As the database names the kind: nonclustered, clustered columnstore, xml, spatial. */
+    type?: string;
+    /** A filtered index's WHERE. */
+    filter?: string;
+    disabled?: boolean;
+    properties?: Properties;
 }
 export interface Constraint {
     name: string;
     kind: 'primary' | 'unique' | 'check' | 'foreign';
     columns: string[];
     definition?: string;
+    /** A foreign key or check the database no longer enforces. */
+    disabled?: boolean;
+    /** Enforced, but not checked against the rows already there, so the optimiser cannot rely on it. */
+    untrusted?: boolean;
+    properties?: Properties;
+}
+export interface Trigger {
+    name: string;
+    timing: 'after' | 'instead of';
+    /** insert, update, delete. */
+    events: string[];
+    enabled: boolean;
+    definition?: string;
+}
+/** A row-level security predicate on the table: a filter hides rows, a block refuses writes. */
+export interface SecurityPredicate {
+    policy: string;
+    kind: 'filter' | 'block';
+    /** For a block predicate: after insert, before update, and so on. */
+    operation?: string;
+    predicate: string;
+    enabled: boolean;
 }
 /**
  * How big a table is, as the database keeps it about itself: counted from its catalogue, never by reading
@@ -44,10 +98,37 @@ export interface Table {
     /** The SQL of a view. */
     definition?: string;
     stats?: TableStats;
+    properties?: Properties;
+    /** When the table was created and its definition last altered, as ISO timestamps. */
+    created?: string;
+    altered?: string;
+    /** A system-versioned table: its history table (a ref) and the columns that bound each row's period. */
+    temporal?: {
+        history: string;
+        start: string;
+        end: string;
+    };
+    /** The history table of a system-versioned table, as its ref. */
+    historyOf?: string;
+    memoryOptimised?: 'schema and data' | 'schema only';
+    ledger?: 'updatable' | 'append-only' | 'history';
+    partitioning?: {
+        scheme: string;
+        function: string;
+        column: string;
+        partitions: number;
+    };
+    /** The table's own compression, when it has any: row, page, columnstore, columnstore archive. */
+    compression?: string;
+    changeTracking?: boolean;
+    cdc?: boolean;
+    triggers?: Trigger[];
+    security?: SecurityPredicate[];
 }
 export interface Schema {
     name: string;
     tables: Table[];
+    properties?: Properties;
 }
 export interface RelationEnd {
     table: string;
@@ -61,6 +142,9 @@ export interface Relation {
     virtual?: boolean;
     onDelete?: string;
     onUpdate?: string;
+    /** As on its constraint: not enforced, or not checked against the rows already there. */
+    disabled?: boolean;
+    untrusted?: boolean;
 }
 export interface Database {
     name: string;
@@ -69,6 +153,11 @@ export interface Database {
     description?: string;
     /** When the source read its tables' stats, as an ISO timestamp: they change, so they carry their moment. */
     statsReadAt?: string;
+    /** The default collation; a column says its own only where it differs. */
+    collation?: string;
+    properties?: Properties;
+    /** What the source could not read and why, so a reader knows an absence is not a no. */
+    unread?: string[];
     schemas: Schema[];
     relations: Relation[];
 }

package/dist/model.js

@@ -114,10 +114,15 @@ function checkDatabase(check, d, p) {
     check.optionalString(d.version, `${p}.version`);
     check.optionalString(d.description, `${p}.description`);
     check.optionalString(d.statsReadAt, `${p}.statsReadAt`);
+    check.optionalString(d.collation, `${p}.collation`);
+    check.properties(d.properties, `${p}.properties`);
+    if (d.unread !== undefined)
+        check.strings(d.unread, `${p}.unread`);
     check.list(d.schemas, `${p}.schemas`, (s, sp) => {
         if (!check.object(s, sp))
             return;
         check.string(s.name, `${sp}.name`);
+        check.properties(s.properties, `${sp}.properties`);
         check.list(s.tables, `${sp}.tables`, (t, tp) => checkTable(check, t, tp));
     });
     check.list(d.relations, `${p}.relations`, (r, rp) => {
@@ -132,6 +137,8 @@ function checkDatabase(check, d, p) {
             check.strings(e.columns, `${rp}.${end}.columns`);
         }
         check.optionalBoolean(r.virtual, `${rp}.virtual`);
+        check.optionalBoolean(r.disabled, `${rp}.disabled`);
+        check.optionalBoolean(r.untrusted, `${rp}.untrusted`);
     });
 }
 function checkTable(check, t, p) {
@@ -148,6 +155,7 @@ function checkTable(check, t, p) {
     }
     if (t.primaryKey !== undefined)
         check.strings(t.primaryKey, `${p}.primaryKey`);
+    checkCatalogue(check, t, p);
     check.list(t.columns, `${p}.columns`, (c, cp) => {
         if (!check.object(c, cp))
             return;
@@ -159,6 +167,18 @@ function checkTable(check, t, p) {
         check.optionalString(c.computed, `${cp}.computed`);
         check.optionalBoolean(c.identity, `${cp}.identity`);
         check.optionalString(c.description, `${cp}.description`);
+        for (const field of ['identitySeed', 'identityIncrement', 'collation', 'masked'])
+            check.optionalString(c[field], `${cp}.${field}`);
+        check.optionalBoolean(c.sparse, `${cp}.sparse`);
+        check.properties(c.properties, `${cp}.properties`);
+        if (c.encrypted !== undefined && check.object(c.encrypted, `${cp}.encrypted`)) {
+            check.oneOf(c.encrypted.type, ['deterministic', 'randomized'], `${cp}.encrypted.type`);
+            check.string(c.encrypted.key, `${cp}.encrypted.key`);
+        }
+        if (c.sensitivity !== undefined && check.object(c.sensitivity, `${cp}.sensitivity`)) {
+            for (const field of ['label', 'informationType', 'rank'])
+                check.optionalString(c.sensitivity[field], `${cp}.sensitivity.${field}`);
+        }
     });
     check.list(t.indexes, `${p}.indexes`, (x, xp) => {
         if (!check.object(x, xp))
@@ -167,6 +187,10 @@ function checkTable(check, t, p) {
         check.strings(x.columns, `${xp}.columns`);
         if (typeof x.unique !== 'boolean')
             check.errors.push(`${xp}.unique must be true or false`);
+        check.optionalString(x.type, `${xp}.type`);
+        check.optionalString(x.filter, `${xp}.filter`);
+        check.optionalBoolean(x.disabled, `${xp}.disabled`);
+        check.properties(x.properties, `${xp}.properties`);
     });
     check.list(t.constraints, `${p}.constraints`, (c, cp) => {
         if (!check.object(c, cp))
@@ -176,8 +200,56 @@ function checkTable(check, t, p) {
             check.errors.push(`${cp}.kind is not a constraint kind`);
         check.strings(c.columns, `${cp}.columns`);
         check.optionalString(c.definition, `${cp}.definition`);
+        check.optionalBoolean(c.disabled, `${cp}.disabled`);
+        check.optionalBoolean(c.untrusted, `${cp}.untrusted`);
+        check.properties(c.properties, `${cp}.properties`);
     });
 }
+/** What the catalogue says about a table beyond its columns, keys and indexes. */
+function checkCatalogue(check, t, p) {
+    check.properties(t.properties, `${p}.properties`);
+    for (const field of ['created', 'altered', 'historyOf', 'compression'])
+        check.optionalString(t[field], `${p}.${field}`);
+    for (const field of ['changeTracking', 'cdc'])
+        check.optionalBoolean(t[field], `${p}.${field}`);
+    if (t.memoryOptimised !== undefined)
+        check.oneOf(t.memoryOptimised, ['schema and data', 'schema only'], `${p}.memoryOptimised`);
+    if (t.ledger !== undefined)
+        check.oneOf(t.ledger, ['updatable', 'append-only', 'history'], `${p}.ledger`);
+    if (t.temporal !== undefined && check.object(t.temporal, `${p}.temporal`)) {
+        for (const field of ['history', 'start', 'end'])
+            check.string(t.temporal[field], `${p}.temporal.${field}`);
+    }
+    if (t.partitioning !== undefined && check.object(t.partitioning, `${p}.partitioning`)) {
+        for (const field of ['scheme', 'function', 'column'])
+            check.string(t.partitioning[field], `${p}.partitioning.${field}`);
+        check.count(t.partitioning.partitions, `${p}.partitioning.partitions`);
+    }
+    if (t.triggers !== undefined) {
+        check.list(t.triggers, `${p}.triggers`, (g, gp) => {
+            if (!check.object(g, gp))
+                return;
+            check.string(g.name, `${gp}.name`);
+            check.oneOf(g.timing, ['after', 'instead of'], `${gp}.timing`);
+            check.strings(g.events, `${gp}.events`);
+            if (typeof g.enabled !== 'boolean')
+                check.errors.push(`${gp}.enabled must be true or false`);
+            check.optionalString(g.definition, `${gp}.definition`);
+        });
+    }
+    if (t.security !== undefined) {
+        check.list(t.security, `${p}.security`, (r, rp) => {
+            if (!check.object(r, rp))
+                return;
+            check.string(r.policy, `${rp}.policy`);
+            check.oneOf(r.kind, ['filter', 'block'], `${rp}.kind`);
+            check.optionalString(r.operation, `${rp}.operation`);
+            check.string(r.predicate, `${rp}.predicate`);
+            if (typeof r.enabled !== 'boolean')
+                check.errors.push(`${rp}.enabled must be true or false`);
+        });
+    }
+}
 class Checker {
     errors;
     constructor(errors) {
@@ -201,6 +273,18 @@ class Checker {
         if (value !== undefined && typeof value !== 'boolean')
             this.errors.push(`${path} must be true or false when given`);
     }
+    properties(value, path) {
+        if (value === undefined || !this.object(value, path))
+            return;
+        for (const [name, text] of Object.entries(value)) {
+            if (typeof text !== 'string')
+                this.errors.push(`${path}.${name} must be a string`);
+        }
+    }
+    oneOf(value, allowed, path) {
+        if (!allowed.includes(value))
+            this.errors.push(`${path} must be ${allowed.map((a) => `"${a}"`).join(' or ')}`);
+    }
     count(value, path) {
         if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
             this.errors.push(`${path} must be a number of 0 or more`);

package/dist/render/markdown.d.ts

@@ -1,8 +1,17 @@
-import { findTable, type Model, type TableStats } from '../model.ts';
+import { findTable, type Model, type Table, type TableStats } from '../model.ts';
 export declare const wholeDiagramLimit = 40;
 export declare function renderMarkdown(model: Model): Record<string, string>;
 /** The product's name for a driver: mssql is SQL Server. */
 export declare function driverName(driver: string): string;
+/** A thing the catalogue says about a table beyond its columns and keys: a name, and its particulars. */
+export interface Feature {
+    name: string;
+    detail?: string;
+    /** A table the detail names, for a link. */
+    ref?: string;
+}
+/** What the catalogue says about a table beyond its columns and keys, in the order a reader weighs it. */
+export declare function features(table: Table): Feature[];
 /** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
 export declare function formatCount(n: number): string;
 /** 480 KB, 7.1 MB, 102 MB: binary units, as the database counts its pages, with one decimal below ten. */

package/dist/render/markdown.js

@@ -27,6 +27,8 @@ function renderIndex(model) {
         if (database.description)
             parts.push(`${database.description}\n`);
         parts.push(`${driverLine(database)}\n`);
+        if (database.unread?.length)
+            parts.push(`Not read: ${database.unread.join('; ')}.\n`);
         // Rows and size only when the source read them; a view, which keeps no rows of its own, leaves them blank.
         const sized = database.schemas.some((s) => s.tables.some((t) => t.stats));
         parts.push(sized ? '| Table | Kind | Columns | Rows | Size | Description |\n|---|---|---|---|---|---|' : '| Table | Kind | Columns | Description |\n|---|---|---|---|');
@@ -39,6 +41,10 @@ function renderIndex(model) {
         }
         parts.push('');
     }
+    const owned = model.databases.flatMap((d) => [[d.name, d.properties], ...d.schemas.map((s) => [s.name, s.properties])]);
+    const properties = propertiesTable(owned);
+    if (properties)
+        parts.push(`## Properties\n\n${properties}`);
     for (const group of model.groups) {
         parts.push(`## ${group.name}\n`);
         if (group.description)
@@ -63,7 +69,81 @@ export function driverName(driver) {
 }
 function driverLine(database) {
     const name = driverName(database.driver);
-    return database.version ? `${name} ${database.version}.` : `${name}.`;
+    const collation = database.collation ? `, collation ${database.collation}` : '';
+    return `${database.version ? `${name} ${database.version}` : name}${collation}.`;
+}
+/** What the catalogue says about a table beyond its columns and keys, in the order a reader weighs it. */
+export function features(table) {
+    const list = [];
+    if (table.temporal) {
+        const { history, start, end } = table.temporal;
+        list.push({ name: 'System-versioned', detail: `history in ${history}, each row valid from ${start} to ${end}`, ref: history });
+    }
+    if (table.historyOf)
+        list.push({ name: 'History', detail: `of ${table.historyOf}`, ref: table.historyOf });
+    if (table.memoryOptimised)
+        list.push({ name: 'Memory-optimised', detail: table.memoryOptimised });
+    if (table.ledger)
+        list.push({ name: 'Ledger', detail: table.ledger });
+    if (table.partitioning) {
+        const { column, scheme, function: fn, partitions } = table.partitioning;
+        list.push({ name: 'Partitioned', detail: `on ${column} by ${scheme} (function ${fn}), ${partitions} partitions` });
+    }
+    // A list is a table whose partitions are compressed differently.
+    if (table.compression)
+        list.push({ name: 'Compressed', detail: table.compression.includes(',') ? `${table.compression}, by partition` : table.compression });
+    if (table.changeTracking)
+        list.push({ name: 'Change tracking' });
+    if (table.cdc)
+        list.push({ name: 'Change data capture' });
+    if (table.triggers?.length)
+        list.push({ name: 'Triggers', detail: String(table.triggers.length) });
+    if (table.security?.length)
+        list.push({ name: 'Row-level security', detail: [...new Set(table.security.map((s) => s.policy))].join(', ') });
+    if (table.created) {
+        const altered = table.altered && table.altered.slice(0, 10) !== table.created.slice(0, 10) ? `, last altered ${table.altered.slice(0, 10)}` : '';
+        list.push({ name: 'Created', detail: `${table.created.slice(0, 10)}${altered}` });
+    }
+    return list;
+}
+/** A column's type, with its collation where it differs from the database's. */
+function columnType(column) {
+    return column.collation ? `${column.type}, collation ${column.collation}` : column.type;
+}
+/** What else the catalogue says about a column, for the Key cell: identity, sparse, masking, encryption. */
+function columnTraits(column) {
+    const traits = [];
+    if (column.identity)
+        traits.push(column.identitySeed !== undefined ? `identity(${column.identitySeed},${column.identityIncrement ?? '1'})` : 'identity');
+    if (column.computed !== undefined)
+        traits.push(`computed \`${column.computed}\``);
+    if (column.sparse)
+        traits.push('sparse');
+    if (column.masked)
+        traits.push(`masked \`${column.masked}\``);
+    if (column.encrypted)
+        traits.push(`encrypted (${column.encrypted.type}, ${column.encrypted.key})`);
+    return traits;
+}
+/** The description cell: the description, then the sensitivity classification when there is one. */
+function columnDescription(column) {
+    const parts = column.description ? [column.description] : [];
+    const s = column.sensitivity;
+    if (s)
+        parts.push(`Sensitivity: ${[s.label, s.informationType, s.rank && `rank ${s.rank}`].filter(Boolean).join(', ')}.`);
+    return parts.join(' ');
+}
+/** Not enforced, or not checked against the rows already there. */
+function enforcement(item) {
+    return [item.disabled ? 'disabled' : '', item.untrusted ? 'not trusted' : ''].filter(Boolean);
+}
+function indexKind(index) {
+    return [index.type ?? '', index.filter ? `filtered \`${index.filter}\`` : '', index.disabled ? 'disabled' : ''].filter(Boolean).join(', ');
+}
+/** Every extended property of the things listed, one row each; empty when there are none. */
+function propertiesTable(owners) {
+    const rows = owners.flatMap(([on, properties]) => Object.entries(properties ?? {}).map(([name, value]) => `| ${cell(on)} | ${cell(name)} | ${cell(value)} |`));
+    return rows.length === 0 ? '' : `| On | Name | Value |\n|---|---|---|\n${rows.join('\n')}\n`;
 }
 /** 1,204,377: thousands grouped the same way wherever it runs, so the docs do not change with the machine. */
 export function formatCount(n) {
@@ -99,6 +179,13 @@ function renderTable(model, ref, table, database) {
         parts.push(`${table.description}\n`);
     if (table.stats)
         parts.push(`${statsLine(table.stats, database.statsReadAt)}\n`);
+    const listed = features(table);
+    if (listed.length > 0) {
+        parts.push('## Features\n');
+        // A table the feature names gets a link when it is in the model, as a relation's would.
+        const linked = (f) => (f.ref && f.detail && findTable(model, f.ref) ? f.detail.replace(f.ref, `[${f.ref}](${f.ref}.md)`) : f.detail);
+        parts.push(listed.map((f) => `- **${f.name}**${f.detail ? `: ${linked(f)}` : ''}`).join('\n') + '\n');
+    }
     const relations = relationsOf(model, ref);
     parts.push('| Column | Type | Nullable | Default | Key | Description |\n|---|---|---|---|---|---|');
     for (const column of table.columns) {
@@ -110,16 +197,14 @@ function renderTable(model, ref, table, database) {
             if (i === -1)
                 continue;
             const { table: toTable, columns } = relation.to;
-            keys.push(`FK → [${toTable}](${toTable}.md).${columns[i] ?? columns.join(',')}${relation.virtual ? ' (notes)' : ''}`);
+            const state = [relation.virtual ? 'notes' : '', ...enforcement(relation)].filter(Boolean);
+            keys.push(`FK → [${toTable}](${toTable}.md).${columns[i] ?? columns.join(',')}${state.length ? ` (${state.join(', ')})` : ''}`);
         }
         if (isUniqueColumn(table, column.name))
             keys.push('unique');
-        if (column.identity)
-            keys.push('identity');
-        if (column.computed !== undefined)
-            keys.push(`computed \`${column.computed}\``);
+        keys.push(...columnTraits(column));
         const dflt = column.default === undefined ? '' : `\`${column.default}\``;
-        parts.push(`| ${cell(column.name)} | ${cell(column.type)} | ${column.nullable ? 'yes' : 'no'} | ${cell(dflt)} | ${keys.join(', ')} | ${cell(column.description)} |`);
+        parts.push(`| ${cell(column.name)} | ${cell(columnType(column))} | ${column.nullable ? 'yes' : 'no'} | ${cell(dflt)} | ${cell(keys.join(', '))} | ${cell(columnDescription(column))} |`);
     }
     parts.push('');
     if (relations.in.length > 0) {
@@ -131,10 +216,12 @@ function renderTable(model, ref, table, database) {
     }
     if (table.indexes.length > 0) {
         parts.push('## Indexes\n');
-        parts.push('| Name | Columns | Unique |\n|---|---|---|');
+        // The Kind column only when the source said what kind; a model without it renders as it always did.
+        const kinds = table.indexes.some((i) => indexKind(i) !== '');
+        parts.push(kinds ? '| Name | Columns | Unique | Kind |\n|---|---|---|---|' : '| Name | Columns | Unique |\n|---|---|---|');
         for (const index of table.indexes) {
             const columns = index.columns.join(', ') + (index.included?.length ? ` (includes ${index.included.join(', ')})` : '');
-            parts.push(`| ${cell(index.name)} | ${cell(columns)} | ${index.unique ? 'yes' : 'no'} |`);
+            parts.push(`| ${cell(index.name)} | ${cell(columns)} | ${index.unique ? 'yes' : 'no'} |${kinds ? ` ${cell(indexKind(index))} |` : ''}`);
         }
         parts.push('');
     }
@@ -143,7 +230,34 @@ function renderTable(model, ref, table, database) {
         parts.push('| Name | Kind | Columns | Definition |\n|---|---|---|---|');
         for (const constraint of table.constraints) {
             const definition = constraint.definition === undefined ? '' : `\`${constraint.definition}\``;
-            parts.push(`| ${cell(constraint.name)} | ${constraint.kind} | ${cell(constraint.columns.join(', '))} | ${cell(definition)} |`);
+            const kind = [constraint.kind, ...enforcement(constraint)].join(', ');
+            parts.push(`| ${cell(constraint.name)} | ${kind} | ${cell(constraint.columns.join(', '))} | ${cell(definition)} |`);
+        }
+        parts.push('');
+    }
+    const properties = propertiesTable([
+        [ref, table.properties],
+        ...table.columns.map((c) => [c.name, c.properties]),
+        ...table.indexes.map((i) => [i.name, i.properties]),
+        ...table.constraints.map((c) => [c.name, c.properties]),
+    ]);
+    if (properties)
+        parts.push(`## Properties\n\n${properties}`);
+    if (table.triggers?.length) {
+        parts.push('## Triggers\n');
+        for (const trigger of table.triggers) {
+            const when = `${trigger.timing === 'after' ? 'After' : 'Instead of'} ${trigger.events.join(', ')}. ${trigger.enabled ? 'Enabled' : 'Disabled'}.`;
+            parts.push(`### ${trigger.name}\n\n${when}\n`);
+            if (trigger.definition)
+                parts.push('```sql\n' + trigger.definition.trim() + '\n```\n');
+        }
+    }
+    if (table.security?.length) {
+        parts.push('## Row-level security\n');
+        parts.push('| Policy | Kind | Predicate | Enabled |\n|---|---|---|---|');
+        for (const s of table.security) {
+            const kind = s.operation ? `${s.kind}, ${s.operation}` : s.kind;
+            parts.push(`| ${cell(s.policy)} | ${kind} | ${cell(`\`${s.predicate}\``)} | ${s.enabled ? 'yes' : 'no'} |`);
         }
         parts.push('');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dbtour",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Tour your database and its API: searchable docs, relations and diagrams, generated from the schema, kept in the repo.",
   "type": "module",
   "license": "MIT",