tablewalk 0.0.1

package/dist/server/changeimpact.js

@@ -0,0 +1,195 @@
+import { findTable, referencesFrom, referencesTo, } from '../shared/schema.js';
+import { inBatches } from './impact.js';
+/**
+ * Read the facts, then say what they mean.
+ *
+ * `column` narrows the question: without it this is "what depends on this
+ * table", with it "what depends on this column" — which is the narrower and
+ * far more common migration. A named column that no foreign key touches still
+ * gets its own facts, because `NOT NULL` and `UNIQUE` are changes that break
+ * on the data rather than on the graph.
+ */
+export async function changeImpact(adapter, schema, tableId, column) {
+    const table = findTable(schema, tableId);
+    if (!table) {
+        throw new Error(`No table called "${tableId}" in this database.`);
+    }
+    const meta = column
+        ? table.columns.find((c) => c.name.toLowerCase() === column.toLowerCase())
+        : undefined;
+    if (column && !meta) {
+        throw new Error(`"${column}" is not a column on ${table.id}. It has: ${table.columns.map((c) => c.name).join(', ')}.`);
+    }
+    /* Narrowed to the named column when there is one: a foreign key pointing at
+       `customer.id` is irrelevant to a change to `customer.email`, and listing
+       it anyway is how a report becomes noise nobody reads to the end of. */
+    const incoming = referencesTo(schema, table.id).filter((fk) => !meta || fk.to.columns.some((c) => c.toLowerCase() === meta.name.toLowerCase()));
+    const outgoing = referencesFrom(schema, table.id).filter((fk) => !meta || fk.from.columns.some((c) => c.toLowerCase() === meta.name.toLowerCase()));
+    /* One count per dependent table, batched. `deleteImpact` bounds its width
+       for the same reason: a dozen unbounded table scans is how one question
+       monopolises the connection everything else is waiting on. */
+    const counts = await inBatches(incoming, 4, async (fk) => {
+        try {
+            return await adapter.count(fk.from.table);
+        }
+        catch {
+            /* A table that cannot be counted — a permission, a view over something
+               missing — must not take the rest of the report down with it. */
+            return undefined;
+        }
+    });
+    const referencedBy = incoming.map((fk, i) => ({
+        constraint: fk.name,
+        table: fk.from.table,
+        columns: fk.from.columns,
+        toColumns: fk.to.columns,
+        onDelete: fk.onDelete,
+        nullable: nullableRef(schema, fk),
+        indexed: indexedRef(schema, fk),
+        rows: counts[i],
+    }));
+    const references = outgoing.map((fk) => ({
+        constraint: fk.name,
+        columns: fk.from.columns,
+        table: fk.to.table,
+        toColumns: fk.to.columns,
+        onDelete: fk.onDelete,
+    }));
+    let rows;
+    try {
+        rows = await adapter.count(table.id);
+    }
+    catch {
+        rows = undefined;
+    }
+    let columnFacts;
+    if (meta) {
+        /* Counted only where it can be non-zero. On a NOT NULL column the answer
+           is already known, and spending a scan to be told zero is a scan the
+           person waiting did not need. */
+        let nulls;
+        if (meta.nullable) {
+            try {
+                nulls = await adapter.count(table.id, {
+                    groups: [[{ column: meta.name, op: 'isNull' }]],
+                });
+            }
+            catch {
+                nulls = undefined;
+            }
+        }
+        columnFacts = {
+            name: meta.name,
+            type: meta.type,
+            nullable: meta.nullable,
+            primaryKey: meta.primaryKey,
+            ...(meta.default !== undefined ? { default: meta.default } : {}),
+            ...(meta.allowed ? { allowed: meta.allowed } : {}),
+            ...(meta.references ? { references: meta.references } : {}),
+            ...(leads(schema, table.id, meta.name) === undefined
+                ? {}
+                : { indexed: leads(schema, table.id, meta.name) }),
+            ...(nulls === undefined ? {} : { nulls }),
+        };
+    }
+    return {
+        table: table.id,
+        ...(meta ? { column: meta.name } : {}),
+        ...(rows === undefined ? {} : { rows }),
+        ...(columnFacts ? { columnFacts } : {}),
+        referencedBy,
+        references,
+        notes: notesFor({
+            table: table.id,
+            ...(meta ? { column: meta.name } : {}),
+            ...(rows === undefined ? {} : { rows }),
+            ...(columnFacts ? { columnFacts } : {}),
+            referencedBy,
+            references,
+            notes: [],
+        }),
+    };
+}
+/** Does an index lead on this column? `undefined` when nobody looked. */
+function leads(schema, tableId, column) {
+    const table = findTable(schema, tableId);
+    if (!table || table.indexed === undefined)
+        return undefined;
+    return table.indexed.some((c) => c.toLowerCase() === column.toLowerCase());
+}
+/** Can every referencing column hold null — so can those rows survive? */
+function nullableRef(schema, fk) {
+    const child = findTable(schema, fk.from.table);
+    if (!child)
+        return false;
+    return fk.from.columns.every((name) => {
+        const col = child.columns.find((c) => c.name.toLowerCase() === name.toLowerCase());
+        /* A column we cannot find is not evidence that it is nullable. */
+        return col ? col.nullable : false;
+    });
+}
+/** Does an index lead on the referencing side? `undefined` when unknown. */
+function indexedRef(schema, fk) {
+    return leads(schema, fk.from.table, fk.from.columns[0]);
+}
+/**
+ * Turn the facts into the sentences somebody would write after reading them.
+ *
+ * Ordered by how much they change the plan: what refuses the change outright,
+ * then what silently destroys data, then what will merely be slow.
+ */
+function notesFor(impact) {
+    const notes = [];
+    const { columnFacts: col, referencedBy, references, rows } = impact;
+    const what = impact.column ? `${impact.table}.${impact.column}` : impact.table;
+    if (col?.primaryKey) {
+        notes.push(`${what} is part of the primary key`
+            + (referencedBy.length
+                ? `, and ${referencedBy.length} table${referencedBy.length === 1 ? '' : 's'} reference it.`
+                : '.'));
+    }
+    /* The change that fails on the data rather than on the graph, and the most
+       common one to get wrong: the column is full of nulls and the migration
+       that adds NOT NULL is written as though it is not. */
+    if (col && col.nullable && !col.primaryKey && col.nulls !== undefined) {
+        const of = rows === undefined ? '' : ` of ${rows.toLocaleString()}`;
+        notes.push(col.nulls > 0
+            ? `${col.nulls.toLocaleString()}${of} rows hold null, so NOT NULL would be refused until they `
+                + `are filled or given a default.`
+            : `No row${of} holds null, so NOT NULL would be accepted today — nothing stops the next insert `
+                + `from breaking that.`);
+    }
+    for (const dep of referencedBy) {
+        const count = dep.rows === undefined ? 'an unknown number of' : dep.rows.toLocaleString();
+        const held = `${count} row${dep.rows === 1 ? '' : 's'} in ${dep.table}`;
+        if (dep.onDelete === 'cascade') {
+            notes.push(`${dep.table}.${dep.columns.join(', ')} cascades: removing what it points at takes ${held} with it, `
+                + `and anything cascading from those.`);
+        }
+        else if (dep.onDelete === 'set null') {
+            notes.push(`${dep.table}.${dep.columns.join(', ')} is set null on delete: ${held} would survive with a hole.`);
+        }
+        else if (dep.onDelete === undefined) {
+            notes.push(`${dep.table}.${dep.columns.join(', ')} points at ${what} and its delete rule was not reported, `
+                + `so what happens to ${held} is unknown rather than nothing.`);
+        }
+        else {
+            notes.push(`${dep.table}.${dep.columns.join(', ')} points at ${what} under \`${dep.onDelete}\`, `
+                + `so the change is refused while ${held} remain${dep.rows === 1 ? 's' : ''}.`);
+        }
+        if (!dep.nullable) {
+            notes.push(`${dep.table}.${dep.columns.join(', ')} is NOT NULL, so those rows cannot be left pointing at nothing.`);
+        }
+        if (dep.indexed === false) {
+            notes.push(`No index leads on ${dep.table}.${dep.columns[0]}, so every check of this constraint scans `
+                + `${dep.rows === undefined ? 'the whole table' : `${dep.rows.toLocaleString()} rows`}.`);
+        }
+    }
+    if (col?.allowed?.length) {
+        notes.push(`The database constrains it to: ${col.allowed.join(', ')}. Widening it means changing that too.`);
+    }
+    if (!referencedBy.length && !references.length) {
+        notes.push(`Nothing in this database references ${what}, so the change is contained to ${impact.table}.`);
+    }
+    return notes;
+}