pipework 0.290.0 → 0.292.0

package/dist/test/function-reads.js

@@ -0,0 +1,202 @@
+import { sql } from '../data/db/sql.js';
+import { quoteIdentifier } from '../data/db/identifiers.js';
+function walk(node, visit) {
+    visit(node);
+    for (const child of node.Plans ?? [])
+        walk(child, visit);
+}
+function qualified(ref) {
+    return ref.schema === 'public' ? ref.name : `${ref.schema}.${ref.name}`;
+}
+/** Rows touched and the shape facts of one EXPLAIN (ANALYZE, VERBOSE, FORMAT JSON) plan. */
+export function measurePlan(root, ref, history, statistics) {
+    const scans = [];
+    let calledAsFunction = false;
+    let cteScan = false;
+    const callText = new RegExp(`(?:^|[^\\w])${ref.name}\\s*\\(`);
+    walk(root, node => {
+        if (node['Relation Name'] !== undefined) {
+            const loops = node['Actual Loops'] ?? 1;
+            const rows = (node['Actual Rows'] ?? 0) + (node['Rows Removed by Filter'] ?? 0) + (node['Rows Removed by Index Recheck'] ?? 0);
+            scans.push({
+                node: node['Node Type'] ?? 'Scan',
+                relation: `${node['Schema'] ?? 'public'}.${node['Relation Name']}`,
+                touched: rows * loops,
+            });
+        }
+        if (node['Node Type'] === 'CTE Scan')
+            cteScan = true;
+        if (node['Function Name'] === ref.name)
+            calledAsFunction = true;
+        for (const [key, value] of Object.entries(node)) {
+            if (key === 'Plans')
+                continue;
+            if ((key === 'Output' || key === 'Function Call' || key.endsWith('Filter') || key === 'Join Filter' || key === 'Index Cond') && callText.test(JSON.stringify(value)))
+                calledAsFunction = true;
+        }
+    });
+    scans.sort((a, b) => b.touched - a.touched);
+    return { history, statistics, touched: scans.reduce((n, s) => n + s.touched, 0), scans, calledAsFunction, cteScan };
+}
+/** Why Postgres would not inline the function, from its catalog row: the settings a plan cannot show. */
+export function catalogProblems(name, c) {
+    if (c === undefined)
+        return [`the function ${name} does not exist in the database. Run the migration that creates it before checking it.`];
+    const problems = [];
+    if (c.config !== null && c.config.length > 0) {
+        problems.push(`${name} has a SET clause (${c.config.join(', ')}). Postgres never inlines a function with a SET clause, so each call is a black box the planner cannot push keys into. ` +
+            'Remove it: a session setting such as jit belongs on the role (`ALTER ROLE app SET jit = off`).');
+    }
+    if (c.language !== 'sql') {
+        problems.push(`${name} is LANGUAGE ${c.language}. Postgres inlines only LANGUAGE sql functions. Write the read as one SELECT; a computation that is not one SELECT is a derivation, not a read.`);
+    }
+    if (c.volatility === 'v')
+        problems.push(`${name} is VOLATILE. Postgres does not inline a volatile function. Declare it STABLE or IMMUTABLE.`);
+    if (c.securityDefiner)
+        problems.push(`${name} is SECURITY DEFINER. Postgres does not inline a security definer function.`);
+    if (c.strict)
+        problems.push(`${name} is STRICT. Postgres does not inline a strict set-returning function.`);
+    return problems;
+}
+async function readCatalog(db, ref) {
+    const signature = `${quoteIdentifier(ref.schema, 'schema')}.${quoteIdentifier(ref.name, 'function')}(${ref.args.join(', ')})`;
+    const rows = await db.execute(sql `
+    select l.lanname as lang, p.provolatile::text as vol, p.proconfig as config, p.prosecdef as secdef, p.proisstrict as strict
+    from pg_proc p join pg_language l on l.oid = p.prolang
+    where p.oid = to_regprocedure(${signature})`);
+    const r = rows[0];
+    return r === undefined ? undefined : { language: r.lang, volatility: r.vol, config: r.config, securityDefiner: r.secdef, strict: r.strict };
+}
+async function explain(db, opts, history, statistics) {
+    const source = opts.fn(...opts.args);
+    return await db.transaction(async (tx) => {
+        // Parallel workers would split the loop counts the measurement multiplies by.
+        await tx.execute(sql `set local max_parallel_workers_per_gather = 0`);
+        // The call is the typed source (or expression) pipe.fn returns, so the plan is the one the caller's own query gets.
+        const query = opts.fn.ref.setReturning
+            ? tx.select().from(source)
+            : sql `select ${source} as value`;
+        const rows = await tx.execute(sql `explain (analyze, verbose, format json) ${query}`);
+        const raw = rows[0]?.['QUERY PLAN'];
+        const parsed = (typeof raw === 'string' ? JSON.parse(raw) : raw);
+        return measurePlan(parsed[0].Plan, opts.fn.ref, history, statistics);
+    });
+}
+async function setAutovacuum(db, tables, on) {
+    for (const t of tables) {
+        try {
+            await db.execute(sql.raw(`alter table ${qualifiedTable(t)} ${on ? 'reset (autovacuum_enabled)' : 'set (autovacuum_enabled = false)'}`));
+        }
+        catch (err) {
+            throw new Error(`[pipework] checkFunctionRead cannot change autovacuum on ${t}: ${err instanceof Error ? err.message : String(err)}\n\n` +
+                '  Fix: run the check as the role that owns the tables (or a superuser). Autovacuum must be off on them for the run, or a background ANALYZE could turn the stale and missing measurements into fresh ones.\n');
+        }
+    }
+}
+function qualifiedTable(table) {
+    const parts = table.split('.');
+    if (parts.length > 2)
+        throw new Error(`[pipework] checkFunctionRead: "${table}" is not a table name; use "schema.table" or "table".`);
+    return parts.map(p => quoteIdentifier(p, 'table')).join('.');
+}
+const where = (m) => m.scans.length === 0 ? '' : ` Largest scan: ${m.scans[0].node} on ${m.scans[0].relation} (${m.scans[0].touched} rows).`;
+/**
+ * Plans one call of a pipework-defined read at two history sizes and under three states of the planner's
+ * statistics, and reports whether it is a key lookup: inlined into the calling query, touching a number of rows
+ * that does not grow with history, and no more of them under stale or missing statistics than after ANALYZE.
+ * Rows touched is counted from `EXPLAIN (ANALYZE)`: each relation scan's rows returned plus rows removed by
+ * filter or recheck, times its loops, summed. A read that touches no rows on the fixture is `not-checked`, never passed.
+ *
+ * The statistics states: after ANALYZE at the small size the large history is seeded without analyzing (stale), then
+ * analyzed (fresh), then the tables' pg_statistic rows are deleted (missing). Deleting them needs a superuser, as the
+ * test cluster's role is; autovacuum is switched off on the tables for the run and restored.
+ */
+export async function checkFunctionRead(db, opts) {
+    const ref = opts.fn.ref;
+    const name = qualified(ref);
+    const [small, large] = opts.history ?? [200, 2000];
+    const relative = opts.tolerance?.relative ?? 0.1;
+    const absolute = opts.tolerance?.absolute ?? 5;
+    const analyze = async () => { for (const t of opts.tables)
+        await db.execute(sql.raw(`analyze ${qualifiedTable(t)}`)); };
+    const problems = catalogProblems(name, await readCatalog(db, ref));
+    const measurements = [];
+    const role = (await db.execute(sql `select current_user::text as role, rolsuper as super from pg_roles where rolname = current_user`))[0];
+    const notChecked = [];
+    if (role?.super !== true) {
+        notChecked.push(`Missing statistics were not checked: role "${role?.role ?? 'unknown'}" is not a superuser, so it cannot delete the tables' pg_statistic rows. ` +
+            'Run the check as a superuser (the disposable test cluster\'s role; PIPEWORK_TEST_SUPERUSER_URL).');
+    }
+    await setAutovacuum(db, opts.tables, false);
+    try {
+        await opts.seed(db, small);
+        await analyze();
+        const freshSmall = await explain(db, opts, small, 'fresh');
+        await opts.seed(db, large);
+        const stale = await explain(db, opts, large, 'stale');
+        await analyze();
+        const freshLarge = await explain(db, opts, large, 'fresh');
+        measurements.push(freshSmall, stale, freshLarge);
+        if (notChecked.length === 0) {
+            for (const t of opts.tables)
+                await db.execute(sql `delete from pg_statistic where starelid = ${qualifiedTable(t)}::regclass`);
+            measurements.push(await explain(db, opts, large, 'missing'));
+        }
+    }
+    finally {
+        await setAutovacuum(db, opts.tables, true);
+    }
+    return judgeFunctionRead(name, problems, measurements, { relative, absolute }, notChecked);
+}
+/**
+ * The verdict on four measurements (fresh at the small history, then stale, fresh and missing at the large one)
+ * and the problems the catalog already named. Pure, so each verdict can be tested without a database.
+ */
+export function judgeFunctionRead(name, catalog, measurements, tolerance, notChecked = []) {
+    const [freshSmall, stale, freshLarge, missing] = measurements;
+    const allowed = (baseline) => baseline * (1 + tolerance.relative) + tolerance.absolute;
+    const problems = [...catalog];
+    const small = freshSmall.history;
+    const large = freshLarge.history;
+    const done = (status) => ({
+        function: name,
+        status: status === 'passed' && notChecked.length > 0 ? 'not-checked' : status,
+        problems: [...problems, ...notChecked],
+        notChecked,
+        measurements,
+    });
+    if (measurements.some(m => m.calledAsFunction)) {
+        if (problems.length === 0) {
+            problems.push(`${name} was not inlined: the plan calls it as a function (a Function Scan), so the planner could not push the call's keys into its body. ` +
+                'Postgres inlines a function only when it is LANGUAGE sql, one SELECT, STABLE or IMMUTABLE, without SET, SECURITY DEFINER or STRICT, and (for a set) the body is a plain query.');
+        }
+        return done('failed');
+    }
+    if (freshLarge.touched === 0) {
+        if (problems.length > 0)
+            return done('failed');
+        problems.push(`${name} was not exercised: the call touched no rows on the fixture at ${large} rows of history. Seed rows for the keys in \`args\` so the read has something to look up.`);
+        return done('not-checked');
+    }
+    if (freshLarge.touched > allowed(freshSmall.touched)) {
+        problems.push(`${name} touched ${freshSmall.touched} rows at ${small} rows of history and ${freshLarge.touched} at ${large}: its rows touched grow with history, so it scans history instead of looking keys up.${where(freshLarge)}` +
+            (freshLarge.cteScan ? ' The plan has a CTE Scan: a MATERIALIZED CTE (or one used twice) is computed in full before the call\'s keys apply; use it once without MATERIALIZED, or write it as a subquery.' : '') +
+            ' Give the read an index on its key columns and filter on them in the body.');
+    }
+    for (const m of [stale, missing]) {
+        if (m !== undefined && m.touched > allowed(freshLarge.touched)) {
+            problems.push(`${name} touched ${m.touched} rows with ${m.statistics} statistics against ${freshLarge.touched} after ANALYZE (at ${large} rows of history): its plan depends on the statistics being current.${where(m)} ` +
+                'Make the plan the only reasonable one: an index on the key columns, and a filter the index serves.');
+        }
+    }
+    return done(problems.length === 0 ? 'passed' : 'failed');
+}
+/** `checkFunctionRead`, throwing a `[pipework]` error unless the read passed; `not-checked` throws too. */
+export async function expectFunctionRead(db, opts) {
+    const report = await checkFunctionRead(db, opts);
+    if (report.status !== 'passed') {
+        throw new Error(`[pipework] function read ${report.function} ${report.status === 'failed' ? 'is not a key lookup' : 'was not checked'}:\n\n${report.problems.map(p => `  - ${p}`).join('\n')}\n`);
+    }
+    return report;
+}
+//# sourceMappingURL=function-reads.js.map

package/dist/test/function-reads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-reads.js","sourceRoot":"","sources":["../../src/test/function-reads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAA;AACvC,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAgE3D,SAAS,IAAI,CAAC,IAAc,EAAE,KAA4B;IACxD,KAAK,CAAC,IAAI,CAAC,CAAA;IACX,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE;QAAE,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;AAC1D,CAAC;AAED,SAAS,SAAS,CAAC,GAAgB;IACjC,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAA;AACzE,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,IAAc,EAAE,GAAgB,EAAE,OAAe,EAAE,UAA2B;IACxG,MAAM,KAAK,GAA0D,EAAE,CAAA;IACvE,IAAI,gBAAgB,GAAG,KAAK,CAAA;IAC5B,IAAI,OAAO,GAAG,KAAK,CAAA;IACnB,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,eAAe,GAAG,CAAC,IAAI,SAAS,CAAC,CAAA;IAC7D,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE;QAChB,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,SAAS,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,CAAA;YACvC,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,+BAA+B,CAAC,IAAI,CAAC,CAAC,CAAA;YAC9H,KAAK,CAAC,IAAI,CAAC;gBACT,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,IAAI,MAAM;gBACjC,QAAQ,EAAE,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,IAAI,CAAC,eAAe,CAAC,EAAE;gBAClE,OAAO,EAAE,IAAI,GAAG,KAAK;aACtB,CAAC,CAAA;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,CAAC,KAAK,UAAU;YAAE,OAAO,GAAG,IAAI,CAAA;QACpD,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,GAAG,CAAC,IAAI;YAAE,gBAAgB,GAAG,IAAI,CAAA;QAC/D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,IAAI,GAAG,KAAK,OAAO;gBAAE,SAAQ;YAC7B,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,YAAY,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;gBAAE,gBAAgB,GAAG,IAAI,CAAA;QAC/L,CAAC;IACH,CAAC,CAAC,CAAA;IACF,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,CAAA;IAC3C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAA;AACrH,CAAC;AAUD,yGAAyG;AACzG,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,CAAsB;IAClE,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,gBAAgB,IAAI,wFAAwF,CAAC,CAAA;IAC1I,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,sBAAsB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,yHAAyH;YACzK,gGAAgG,CACjG,CAAA;IACH,CAAC;IACD,IAAI,CAAC,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,gBAAgB,CAAC,CAAC,QAAQ,iJAAiJ,CAAC,CAAA;IACnM,CAAC;IACD,IAAI,CAAC,CAAC,UAAU,KAAK,GAAG;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,6FAA6F,CAAC,CAAA;IAC7I,IAAI,CAAC,CAAC,eAAe;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,6EAA6E,CAAC,CAAA;IAC1H,IAAI,CAAC,CAAC,MAAM;QAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,uEAAuE,CAAC,CAAA;IAC3G,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,EAAsB,EAAE,GAAgB;IACjE,MAAM,SAAS,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAA;IAC7H,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAA2F,GAAG,CAAA;;;oCAGzF,SAAS,GAAG,CAAC,CAAA;IAC/C,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAA;AAC7I,CAAC;AAED,KAAK,UAAU,OAAO,CAAC,EAAsB,EAAE,IAAyB,EAAE,OAAe,EAAE,UAA2B;IACpH,MAAM,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,OAAO,MAAM,EAAE,CAAC,WAAW,CAAC,KAAK,EAAC,EAAE,EAAC,EAAE;QACrC,8EAA8E;QAC9E,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,+CAA+C,CAAC,CAAA;QACpE,oHAAoH;QACpH,MAAM,KAAK,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,YAAY;YACpC,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,MAAwE,CAAC;YAC5F,CAAC,CAAC,GAAG,CAAA,UAAU,MAAwB,WAAW,CAAA;QACpD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAA4B,GAAG,CAAA,2CAA2C,KAAuB,EAAE,CAAC,CAAA;QACjI,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAA;QACnC,MAAM,MAAM,GAAG,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAyB,CAAA;QACxF,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;IACvE,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,KAAK,UAAU,aAAa,CAAC,EAAsB,EAAE,MAAyB,EAAE,EAAW;IACzF,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,eAAe,cAAc,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC,CAAC,kCAAkC,EAAE,CAAC,CAAC,CAAA;QACzI,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,4DAA4D,CAAC,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM;gBACxH,8MAA8M,CAC/M,CAAA;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAa;IACnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAC9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,KAAK,uDAAuD,CAAC,CAAA;IACrI,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC9D,CAAC;AAED,MAAM,KAAK,GAAG,CAAC,CAA0B,EAAU,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,QAAQ,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,OAAO,SAAS,CAAA;AAEhL;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EAAsB,EAAE,IAAyB;IACvF,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,CAAA;IACvB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IAC3B,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,IAAI,GAAG,CAAA;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,IAAI,CAAC,CAAA;IAC9C,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE,GAAG,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM;QAAE,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA,CAAC,CAAC,CAAA;IAErI,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,MAAM,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC,CAAA;IAClE,MAAM,YAAY,GAA8B,EAAE,CAAA;IAClD,MAAM,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC,OAAO,CAAmC,GAAG,CAAA,iGAAiG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC1K,MAAM,UAAU,GAAa,EAAE,CAAA;IAC/B,IAAI,IAAI,EAAE,KAAK,KAAK,IAAI,EAAE,CAAC;QACzB,UAAU,CAAC,IAAI,CACb,8CAA8C,IAAI,EAAE,IAAI,IAAI,SAAS,2EAA2E;YAChJ,kGAAkG,CACnG,CAAA;IACH,CAAC;IAED,MAAM,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QAC1B,MAAM,OAAO,EAAE,CAAA;QACf,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;QAC1D,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAA;QAC1B,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;QACrD,MAAM,OAAO,EAAE,CAAA;QACf,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;QAC1D,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,CAAC,CAAA;QAChD,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM;gBAAE,MAAM,EAAE,CAAC,OAAO,CAAC,GAAG,CAAA,6CAA6C,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;YAC5H,YAAY,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAA;QAC9D,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,aAAa,CAAC,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC5C,CAAC;IAED,OAAO,iBAAiB,CAAC,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,UAAU,CAAC,CAAA;AAC5F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,OAA0B,EAC1B,YAAgD,EAChD,SAAmE,EACnE,aAAgC,EAAE;IAElC,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,YAAgI,CAAA;IACjL,MAAM,OAAO,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC,QAAQ,CAAA;IACtG,MAAM,QAAQ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAA;IAC7B,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAA;IAChC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAA;IAChC,MAAM,IAAI,GAAG,CAAC,MAAoC,EAAsB,EAAE,CAAC,CAAC;QAC1E,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,MAAM,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM;QAC7E,QAAQ,EAAE,CAAC,GAAG,QAAQ,EAAE,GAAG,UAAU,CAAC;QACtC,UAAU;QACV,YAAY;KACb,CAAC,CAAA;IAEF,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,oIAAoI;gBAC3I,gLAAgL,CACjL,CAAA;QACH,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAA;IACvB,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAC7B,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAA;QAC9C,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,kEAAkE,KAAK,4FAA4F,CAAC,CAAA;QACzL,OAAO,IAAI,CAAC,aAAa,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACrD,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,YAAY,UAAU,CAAC,OAAO,YAAY,KAAK,wBAAwB,UAAU,CAAC,OAAO,OAAO,KAAK,wFAAwF,KAAK,CAAC,UAAU,CAAC,EAAE;YACvN,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,kLAAkL,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9M,4EAA4E,CAC7E,CAAA;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YAC/D,QAAQ,CAAC,IAAI,CACX,GAAG,IAAI,YAAY,CAAC,CAAC,OAAO,cAAc,CAAC,CAAC,UAAU,uBAAuB,UAAU,CAAC,OAAO,sBAAsB,KAAK,uEAAuE,KAAK,CAAC,CAAC,CAAC,GAAG;gBAC5M,oGAAoG,CACrG,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAC1D,CAAC;AAED,2GAA2G;AAC3G,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EAAsB,EAAE,IAAyB;IACxF,MAAM,MAAM,GAAG,MAAM,iBAAiB,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAChD,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,4BAA4B,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,iBAAiB,QAAQ,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnM,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/test/index.d.ts

@@ -10,4 +10,5 @@ export { pipework as vitestPlugin, type PipeworkVitestOptions } from './vitest-p
 export { resolveVitestConfig, resolveVitestModules } from './vitest-workspace.js';
 export { tap, type ManagedConnection, type ConnectOptions } from '../data/db/pool.js';
 export { crawlFixtureSite, type CrawlFixtureOptions, type CrawlFixtureRoute, type CrawlFixtureRequest, type CrawlFixtureSite } from './crawl-fixture.js';
+export { checkFunctionRead, expectFunctionRead, judgeFunctionRead, measurePlan, catalogProblems, type FunctionReadOptions, type FunctionReadReport, type FunctionReadMeasurement, type StatisticsState } from './function-reads.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/test/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/I,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,YAAY,EACZ,aAAa,EACb,yBAAyB,EACzB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAClH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AACtO,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,EAAE,GAAG,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,eAAe,EAAE,gBAAgB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/I,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,YAAY,EACZ,aAAa,EACb,yBAAyB,EACzB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,qBAAqB,GAC3B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAClH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AACtO,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,EAAE,GAAG,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,KAAK,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACxJ,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,KAAK,uBAAuB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/test/index.js

@@ -10,4 +10,5 @@ export { pipework as vitestPlugin } from './vitest-plugin.js';
 export { resolveVitestConfig, resolveVitestModules } from './vitest-workspace.js';
 export { tap } from '../data/db/pool.js';
 export { crawlFixtureSite } from './crawl-fixture.js';
+export { checkFunctionRead, expectFunctionRead, judgeFunctionRead, measurePlan, catalogProblems } from './function-reads.js';
 //# sourceMappingURL=index.js.map

package/dist/test/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,eAAe,EAAE,gBAAgB,EAAwC,MAAM,YAAY,CAAA;AAC/I,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,YAAY,EACZ,aAAa,EACb,yBAAyB,GAI1B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAwB,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAkD,MAAM,aAAa,CAAA;AAClH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAA6B,qBAAqB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAA;AACtO,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,QAAQ,IAAI,YAAY,EAA8B,MAAM,oBAAoB,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,EAAE,GAAG,EAA+C,MAAM,oBAAoB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAqG,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/test/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,eAAe,EAAE,gBAAgB,EAAwC,MAAM,YAAY,CAAA;AAC/I,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC1F,OAAO,EACL,YAAY,EACZ,aAAa,EACb,yBAAyB,GAI1B,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAwB,MAAM,YAAY,CAAA;AACtF,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAkD,MAAM,aAAa,CAAA;AAClH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAA6B,qBAAqB,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAA;AACtO,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AAC9C,OAAO,EAAE,WAAW,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAA;AACnF,OAAO,EAAE,QAAQ,IAAI,YAAY,EAA8B,MAAM,oBAAoB,CAAA;AACzF,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AACjF,OAAO,EAAE,GAAG,EAA+C,MAAM,oBAAoB,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAqG,MAAM,oBAAoB,CAAA;AACxJ,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,WAAW,EAAE,eAAe,EAAyG,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.290.0",
+  "version": "0.292.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",
@@ -210,7 +210,7 @@
     "mutate": "stryker run",
     "rust:fmt": "cargo fmt --all --check",
     "rust:clippy": "cargo clippy --workspace --all-targets -- -D warnings && cargo clippy -p pipework-query --all-targets --no-default-features --features all-types,audit,hashable-value,serde,thread-safe,postgres-driver -- -D warnings",
-    "rust:test": "cargo test --workspace && cargo test -p pipework-query --features all-types,hashable-value,serde",
+    "rust:test": "set -a; [ ! -f .env.test.local ] || . ./.env.test.local; set +a; cargo test --workspace && cargo test -p pipework-query --features all-types,hashable-value,serde",
     "rust:check": "pnpm rust:fmt && pnpm rust:clippy && pnpm rust:test"
   }
 }

package/src/auth/tenant/scoped-db.ts

@@ -34,6 +34,19 @@ export function unscopedExecutor(db: DB): { readonly db: DB; readonly tenant: st
   return scoped === undefined ? { db, tenant: null } : { db: scoped.raw, tenant: scoped.tenantId }
 }
 
+/**
+ * For a batch insert that writes its own SQL: runs the connection's policy for an insert into `table` (a guard,
+ * `pipe.system()` or a door refuses a tenant table exactly as `insert(table)` does) and returns the tenant column
+ * and value the rows must carry, or null when the table is not tenant-scoped or the handle has no tenant.
+ */
+export function insertTenant(db: DB, table: unknown): { readonly columnKey: string; readonly tenantId: string } | null {
+  ;(db as unknown as { insert: (t: unknown) => unknown }).insert(table)
+  const scoped = scopedHandles.get(db as object)
+  if (scoped === undefined) return null
+  const config = getScopeConfig(table as PgTable)
+  return config === null ? null : { columnKey: config.columnKey, tenantId: scoped.tenantId }
+}
+
 /** The API's name and why it cannot be confined to one tenant, for the error a scoped handle gets. */
 function refuseScopedMessage(api: string, tenant: string, reason: string): string {
   return (

package/src/data/db/function-definition.ts

@@ -0,0 +1,172 @@
+import { blankLiterals, stripComments } from '../migrate/statements.js'
+
+/** Marks a callable returned by `pipe.fn` that carries a definition (a `body`), so the migration generator can find it among a schema file's exports. */
+export const FUNCTION_DEFINITION = Symbol.for('pipework.fn.definition')
+
+export type FunctionVolatility = 'stable' | 'immutable'
+
+/** One column of a set-returning function's result, as the snapshot and the DDL carry it. */
+export interface FunctionColumnDefinition {
+  readonly name: string
+  readonly type: string
+}
+
+/** A function pipework creates and migrates: what the snapshot records and the DDL is emitted from. */
+export interface FunctionDefinition {
+  readonly schema: string
+  readonly name: string
+  /** SQL types of the arguments, in call order. */
+  readonly args: readonly string[]
+  /** `table`: RETURNS TABLE(columns) with a ROWS estimate. `scalar`: RETURNS type. */
+  readonly returns:
+    | { readonly kind: 'table'; readonly columns: readonly FunctionColumnDefinition[]; readonly rows: number }
+    | { readonly kind: 'scalar'; readonly type: string }
+  readonly body: string
+  readonly volatility: FunctionVolatility
+}
+
+/** What `pipe.fn` was given, for the rules that look at it before it becomes a definition. */
+export interface FunctionDefinitionInput {
+  readonly name: string
+  readonly argCount: number
+  readonly body: string
+  readonly spec: Readonly<Record<string, unknown>>
+  readonly setReturning: boolean
+}
+
+const SPEC_KEYS = new Set(['args', 'columns', 'returns', 'body', 'volatility', 'rows', 'language'])
+
+function fail(name: string, message: string, fix: string): never {
+  throw new Error(`[pipework] pipe.fn("${name}"): ${message}\n\n  Fix: ${fix}\n`)
+}
+
+/** The identity of a function in a snapshot: `schema.name(type, type)`; a changed argument list is a different function. */
+export function functionKey(def: Pick<FunctionDefinition, 'schema' | 'name' | 'args'>): string {
+  return `${def.schema}.${def.name}(${def.args.join(', ')})`
+}
+
+/**
+ * The static rules of a pipework-defined read. Each exists because Postgres inlines a SQL function into the
+ * calling query only when the function allows it, and a function that is not inlined is a black box the planner
+ * cannot push the caller's keys into; its rows touched then grow with history instead of with its keys.
+ * Throws a `[pipework]` error naming the rule and the fix.
+ */
+export function assertReadFunction(input: FunctionDefinitionInput): void {
+  const { name, spec, body } = input
+
+  for (const key of ['set', 'config', 'settings']) {
+    if (key in spec) {
+      fail(
+        name,
+        `"${key}" is a SET clause, which a read function cannot have. Postgres never inlines a function with a SET clause (proconfig is set), so the planner cannot push the caller's keys into it and every call plans and scans on its own.`,
+        'remove it. A session setting such as jit belongs on the role (`ALTER ROLE app SET jit = off`), not on a function.',
+      )
+    }
+  }
+  const unknown = Object.keys(spec).filter(k => !SPEC_KEYS.has(k) && k !== 'set' && k !== 'config' && k !== 'settings')
+  if (unknown.length > 0) {
+    fail(
+      name,
+      `unknown option${unknown.length > 1 ? 's' : ''} ${unknown.map(k => `"${k}"`).join(', ')}.`,
+      `a read function takes ${[...SPEC_KEYS].join(', ')}. SECURITY DEFINER, STRICT, PARALLEL and COST are not offered: each stops Postgres inlining the function.`,
+    )
+  }
+
+  const language = spec['language']
+  if (language !== undefined && language !== 'sql') {
+    fail(
+      name,
+      `language "${String(language)}" is not allowed for a read. Postgres inlines only LANGUAGE sql functions; a plpgsql function is a black box that runs per call and cannot be pushed into.`,
+      'write the read as one LANGUAGE sql SELECT. A computation that cannot be one SELECT is a derivation (maintained on write), not a read.',
+    )
+  }
+
+  const volatility = spec['volatility']
+  if (volatility !== undefined && volatility !== 'stable' && volatility !== 'immutable') {
+    fail(
+      name,
+      `volatility "${String(volatility)}" is not allowed for a read. Postgres does not inline a VOLATILE function into the calling query.`,
+      "use 'stable' (reads tables) or 'immutable' (reads nothing that changes).",
+    )
+  }
+
+  if (input.setReturning) {
+    const rows = spec['rows']
+    if (typeof rows !== 'number' || !Number.isInteger(rows) || rows <= 0) {
+      fail(
+        name,
+        'a set-returning function needs a ROWS estimate (a positive integer). Without it Postgres assumes 1000 rows for the call, and plans every join and filter around that guess.',
+        'give `rows` the typical result size for one call, e.g. `rows: 50`.',
+      )
+    }
+  } else if (spec['rows'] !== undefined) {
+    fail(name, '`rows` applies to a set-returning function, and this one returns a scalar.', 'remove `rows`, or declare `columns` to return a set.')
+  }
+
+  const code = blankLiterals(stripComments(body))
+  const trimmed = code.trim().replace(/;\s*$/, '')
+
+  if (/;/.test(trimmed)) {
+    fail(
+      name,
+      'the body has more than one statement. Postgres inlines a function only when its body is a single SELECT.',
+      'make the body one SELECT (use a CTE or a join for the second step).',
+    )
+  }
+  if (!/^(select|with|\(\s*select)\b/i.test(trimmed)) {
+    fail(
+      name,
+      'the body is not a SELECT. A read function is one SELECT statement; Postgres inlines only a single SELECT.',
+      'start the body with SELECT or WITH ... SELECT.',
+    )
+  }
+  if (/\b(insert\s+into|update\s+[\w".]+\s+set|delete\s+from|merge\s+into|truncate\s+(?:table\s+)?["\w])/i.test(trimmed)) {
+    fail(
+      name,
+      'the body writes (INSERT, UPDATE, DELETE, MERGE or TRUNCATE, possibly inside a CTE). A read function is one SELECT; a body with a data-modifying statement is not inlined.',
+      'move the write to pipe.insert / pipe.update / pipe.delete.',
+    )
+  }
+  if (/\bfor\s+(no\s+key\s+update|update|key\s+share|share)\b/i.test(trimmed)) {
+    fail(name, 'the body takes row locks (FOR UPDATE / FOR SHARE). Postgres does not inline a function that locks rows.', 'remove the locking clause; a read does not lock.')
+  }
+  if (/\bset_config\s*\(/i.test(trimmed)) {
+    fail(
+      name,
+      'the body calls set_config(), which is a SET clause in disguise: it makes the function VOLATILE and Postgres does not inline it.',
+      'remove it. A session setting belongs on the role (`ALTER ROLE app SET ... `).',
+    )
+  }
+  if (/\bas\s+materialized\b/i.test(trimmed)) {
+    fail(
+      name,
+      'the body has a MATERIALIZED CTE. Postgres computes it once, in full, before the caller\'s keys are applied: it is an optimisation fence, and the rows it scans grow with history, not with the keys.',
+      'drop the MATERIALIZED keyword (a CTE used once is inlined by default), or write the CTE as a subquery or a join.',
+    )
+  }
+  if (/\bin\s*\(\s*\$\d+\s*(?:,\s*\$\d+\s*)+\)/i.test(trimmed) || /\barray\s*\[\s*\$\d+\s*(?:,\s*\$\d+\s*)+\]/i.test(trimmed)) {
+    fail(
+      name,
+      'a list is passed as separate parameters ($1, $2, ...). A list argument is one array parameter: separate parameters give every list length its own signature and its own plan.',
+      'declare one array argument (`pipe.field.uuid().array()`) and write `column = ANY($n)`.',
+    )
+  }
+  for (const m of trimmed.matchAll(/\$(\d+)/g)) {
+    const n = Number(m[1])
+    if (n < 1 || n > input.argCount) {
+      fail(
+        name,
+        `the body refers to $${n}, but the function declares ${input.argCount} argument${input.argCount === 1 ? '' : 's'}.`,
+        'refer to arguments as $1 ... $n, in the order of `args`.',
+      )
+    }
+  }
+}
+
+/** The dollar-quote tag for a body: `$pw_body$`, lengthened until the body does not contain it. */
+export function bodyQuote(body: string): string {
+  let tag = '$pw_body$'
+  let i = 0
+  while (body.includes(tag)) tag = `$pw_body${++i}$`
+  return tag
+}

package/src/data/db/function-source.ts

@@ -9,6 +9,7 @@ import type { InferFieldOutput } from '../domain/brand.js'
 import type { FieldDescriptor } from '../domain/types.js'
 import { projectTable } from '../domain/build-table.js'
 import { camelToSnake } from '../domain/naming.js'
+import { assertReadFunction, FUNCTION_DEFINITION, type FunctionDefinition, type FunctionVolatility } from './function-definition.js'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variance-safe bound for descriptors with any output/flags
 type AnyField = FieldDescriptor<any, any>
@@ -21,6 +22,38 @@ export interface FunctionSpec<TArgs extends readonly AnyField[], TColumns extend
   readonly args: readonly [...TArgs]
   /** One `pipe.field.*` descriptor per result column; keys are camelCase, columns are their snake_case. */
   readonly columns: TColumns
+  /** The body of a function pipework creates: one `LANGUAGE sql` SELECT that refers to the arguments as `$1`, `$2`, ... Without it the function is only referenced (it exists already). */
+  readonly body?: string
+  /** `'stable'` (the default) or `'immutable'`; a read is never volatile. Only with `body`. */
+  readonly volatility?: FunctionVolatility
+  /** The typical number of rows one call returns, a planner estimate (ROWS). Required with `body`. */
+  readonly rows?: number
+  /** Only `'sql'`: Postgres inlines no other language. */
+  readonly language?: 'sql'
+}
+
+/** Declares a SQL function that returns one value. See {@link fn}. */
+export interface ScalarFunctionSpec<TArgs extends readonly AnyField[], TReturn extends AnyField> {
+  readonly args: readonly [...TArgs]
+  readonly returns: TReturn
+  readonly body: string
+  readonly volatility?: FunctionVolatility
+  readonly language?: 'sql'
+}
+
+/** A function callable with typed arguments; `definition` is set when pipework creates it (the spec had a `body`). */
+export type DefinedCall<TCall> = TCall & {
+  readonly definition: FunctionDefinition | undefined
+  /** Where the function lives and its argument types; what a plan or catalog check looks it up by. */
+  readonly ref: FunctionRef
+}
+
+/** A function's schema, name and SQL argument types. */
+export interface FunctionRef {
+  readonly schema: string
+  readonly name: string
+  readonly args: readonly string[]
+  readonly setReturning: boolean
 }
 
 /** A column whose data type is `T` (and that cannot be null unless `T` can). */
@@ -56,7 +89,7 @@ function quote(name: string): string {
 }
 
 /**
- * Declares a set-returning SQL function and returns a callable that yields a source for `.from()` and joins.
+ * Declares a SQL function and returns a callable. A set-returning one (`columns`) yields a source for `.from()` and joins.
  * Each argument is a value, a column or a SQL expression of the declared type. A value is bound as a parameter,
  * converted the way a column of that field is on insert (jsonb as JSON text, dates, bigints, arrays), and cast to its
  * declared SQL type: `ext.f($1::uuid, $2::text)`. A null binds SQL NULL. An array argument (`field.uuid().array()`) is
@@ -64,10 +97,15 @@ function quote(name: string): string {
  * `unnest(t.arr::uuid[])`, so an array column can be unnested in a lateral join (`.crossJoinLateral(unnestUuids(t.arr))`).
  * Result columns are typed from `columns`; the default alias is the function's unqualified name.
  */
+export function fn<const TArgs extends readonly AnyField[], TReturn extends AnyField>(
+  name: string,
+  spec: ScalarFunctionSpec<TArgs, TReturn>,
+): DefinedCall<(...values: ArgValues<TArgs>) => SQL<InferFieldOutput<TReturn>>>
 export function fn<const TArgs extends readonly AnyField[], TColumns extends Record<string, AnyField>>(
   name: string,
   spec: FunctionSpec<TArgs, TColumns>,
-): (...values: ArgValues<TArgs>) => FunctionSource<string, TColumns> {
+): DefinedCall<(...values: ArgValues<TArgs>) => FunctionSource<string, TColumns>>
+export function fn(name: string, spec: FunctionSpec<readonly AnyField[], Record<string, AnyField>> | ScalarFunctionSpec<readonly AnyField[], AnyField>): unknown {
   const parts = name.split('.')
   if (parts.length > 2 || parts.some(p => !NAME_PART.test(p))) {
     fail(
@@ -75,29 +113,58 @@ export function fn<const TArgs extends readonly AnyField[], TColumns extends Rec
       'use "fn" or "schema.fn", each part lowercase letters, digits and underscores, not starting with a digit.',
     )
   }
-  const keys = Object.keys(spec.columns)
-  if (keys.length === 0) fail(`pipe.fn("${name}"): columns is empty.`, 'declare at least one result column.')
+  const scalar = 'returns' in spec ? spec.returns : undefined
+  const columns: Record<string, AnyField> = 'columns' in spec ? spec.columns : {}
+  const keys = Object.keys(columns)
+  if (scalar === undefined && keys.length === 0) fail(`pipe.fn("${name}"): columns is empty.`, 'declare at least one result column.')
+  if (scalar !== undefined && 'columns' in spec) fail(`pipe.fn("${name}"): both returns and columns are declared.`, 'declare `returns` for a scalar function or `columns` for a set-returning one.')
   for (const key of keys) {
     if (key === 'as' || key === '_') {
       fail(`pipe.fn("${name}"): a result column cannot be named "${key}".`, 'rename the key; the column name comes from camelToSnake(key).')
     }
   }
 
+  const sqlTypeOf = (fields: Record<string, AnyField>): Record<string, string> => {
+    const cols = getTableColumns(projectTable('pw_fn_args', fields, {})) as Record<string, { getSQLType(): string }>
+    return Object.fromEntries(Object.entries(cols).map(([k, c]) => {
+      const t = c.getSQLType()
+      return [k, t === 'serial' ? 'integer' : t === 'bigserial' ? 'bigint' : t]
+    }))
+  }
+
   const argFields: Record<string, AnyField> = {}
   spec.args.forEach((a, i) => { argFields[`a${i}`] = a })
   const argCols = getTableColumns(projectTable('pw_fn_args', argFields, {})) as Record<string, { getSQLType(): string; mapToDriverValue(value: unknown): unknown }>
-  const argTypes = spec.args.map((_, i) => {
-    const t = argCols[`a${i}`]!.getSQLType()
-    return t === 'serial' ? 'integer' : t === 'bigserial' ? 'bigint' : t
-  })
+  const argTypes = spec.args.map((_, i) => sqlTypeOf({ a: spec.args[i]! })['a']!)
+
+  let definition: FunctionDefinition | undefined
+  if (spec.body !== undefined) {
+    if (typeof spec.body !== 'string') fail(`pipe.fn("${name}"): body must be a string.`, 'pass the SELECT as a string, with arguments as $1, $2, ...')
+    assertReadFunction({ name, argCount: spec.args.length, body: spec.body, spec: spec as unknown as Record<string, unknown>, setReturning: scalar === undefined })
+    const returnTypes = scalar === undefined ? sqlTypeOf(columns) : sqlTypeOf({ r: scalar })
+    definition = {
+      schema: parts.length === 2 ? parts[0]! : 'public',
+      name: parts[parts.length - 1]!,
+      args: argTypes,
+      returns: scalar === undefined
+        ? { kind: 'table', columns: keys.map(k => ({ name: camelToSnake(k), type: returnTypes[k]! })), rows: (spec as FunctionSpec<readonly AnyField[], Record<string, AnyField>>).rows! }
+        : { kind: 'scalar', type: returnTypes['r']! },
+      body: spec.body,
+      volatility: spec.volatility ?? 'stable',
+    }
+  } else {
+    for (const key of ['volatility', 'rows', 'language'] as const) {
+      if (key in spec) fail(`pipe.fn("${name}"): "${key}" is given without a body.`, 'add `body` to have pipework create the function, or remove the option (a referenced function keeps what it was created with).')
+    }
+  }
 
   const fnSql = sql.raw(parts.map(quote).join('.'))
   const defaultAlias = parts[parts.length - 1]!
+  const argList = (values: readonly unknown[]): SQL => sql.join(values.map((v, i) => sql`${bindIfParam(v, argCols[`a${i}`] as unknown as Column)}::${sql.raw(argTypes[i]!)}`), sql`, `)
 
-  const build = (values: readonly unknown[], alias: string): FunctionSource<string, TColumns> => {
+  const build = (values: readonly unknown[], alias: string): FunctionSource<string, Record<string, AnyField>> => {
     const columnList = sql.join(keys.map(k => sql.raw(quote(camelToSnake(k)))), sql`, `)
-    const argList = sql.join(values.map((v, i) => sql`${bindIfParam(v, argCols[`a${i}`] as unknown as Column)}::${sql.raw(argTypes[i]!)}`), sql`, `)
-    const inner = sql`select ${columnList} from ${fnSql}(${argList})`
+    const inner = sql`select ${columnList} from ${fnSql}(${argList(values)})`
     const fields: Record<string, SQL> = {}
     for (const k of keys) {
       fields[k] = sql.raw(`${quote(alias)}.${quote(camelToSnake(k))}`)
@@ -109,16 +176,21 @@ export function fn<const TArgs extends readonly AnyField[], TColumns extends Rec
         if (prop === 'as') return (next: string) => build(values, next)
         return selection.get(target, prop)
       },
-    }) as unknown as FunctionSource<string, TColumns>
+    }) as unknown as FunctionSource<string, Record<string, AnyField>>
   }
 
-  return (...values: ArgValues<TArgs>) => {
+  const call = (...values: unknown[]): unknown => {
     if (values.length !== spec.args.length) {
       fail(
         `pipe.fn("${name}"): called with ${values.length} argument(s), declared ${spec.args.length}.`,
         'pass one value per declared argument.',
       )
     }
-    return build(values, defaultAlias)
+    return scalar !== undefined ? sql`${fnSql}(${argList(values)})` : build(values, defaultAlias)
   }
+  return Object.defineProperties(call, {
+    definition: { value: definition, enumerable: true },
+    ref: { value: { schema: parts.length === 2 ? parts[0]! : 'public', name: defaultAlias, args: argTypes, setReturning: scalar === undefined }, enumerable: true },
+    [FUNCTION_DEFINITION]: { value: definition },
+  })
 }