pipework 0.289.0 → 0.291.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":"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"}

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.289.0",
+  "version": "0.291.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/data/db/expressions.ts

@@ -1,7 +1,7 @@
 import { sql } from './sql.js'
 import type { SQL, Column } from './types.js'
 import type { SQLWrapper } from '../query/sql/sql.js'
-import { bindIfParam } from '../query/index.js'
+import { and, bindIfParam, gte, lte, Row, type RowElement } from '../query/index.js'
 import { PgArray } from '../query/pg-core/index.js'
 import { quoteCollation, type CollationName } from '../query/collation.js'
 import { is } from '../query/entity.js'
@@ -486,3 +486,31 @@ export function walReplayLsn(): SQL<string | null> {
 export function replicaFresh(createdLsn: string | Column | SQL): SQL<boolean | null> {
   return sql<boolean | null>`pg_last_wal_replay_lsn() >= ${createdLsn}::pg_lsn`
 }
+
+/**
+ * A row constructor `(e1, e2, ...)` for comparing composite keys: `eq` / `ne` / `gt` / `gte` / `lt` / `lte`
+ * accept a row on both sides (row against row, equal length), so a composite-key join needs no `pipe.sql`:
+ * `gte(row(t.a, t.b), row(k.a, k.b))` renders `("t"."a", "t"."b") >= ("k"."a", "k"."b")`.
+ * Each element is a column, a SQL expression (a `pipe.rows` column is one) or a bound JS value. A column or
+ * expression is embedded as written. A value is bound and, when the element facing it on the other side is
+ * a column, converted by that column's driver mapping and cast to its SQL type (`$1::text`); facing an
+ * expression it is bound without a cast and Postgres infers its type from the other side.
+ * Throws `[pipework] row:` for fewer than two elements, for rows of unequal length, and when a row is
+ * compared with a non-row.
+ */
+export function row(...elements: RowElement[]): Row {
+  return new Row(elements)
+}
+
+/**
+ * Row equality as the range pair `lhs >= rhs and lhs <= rhs`, for a composite-key match that must use an index.
+ * Written as `(a, b, c) = (x, y, z)` Postgres splits it into three equalities, and a join then probes the shortest
+ * index holding a and b and filters c. A row comparison is a btree index condition only on an index holding all
+ * its columns in order, so the range pair takes the index over (a, b, c) and reads only the matching rows.
+ * It equals equality for keys that are never NULL. With a NULL element a match is never true, as with
+ * equality (a NULL-bearing key does not match itself), but the result can be NULL where equality gives
+ * false, which differs only under `not(...)`; keep NULL-able columns out of the row or filter them first.
+ */
+export function rowEquals(lhs: Row, rhs: Row): SQL<boolean> {
+  return and(gte(lhs, rhs), lte(lhs, rhs)) as SQL<boolean>
+}

package/src/data/db/filter.ts

@@ -5,7 +5,7 @@ import {
 } from '../query/index.js'
 import { countAgg, countDistinctAgg, sumAgg, sumDistinctAgg, avgAgg, avgDistinctAgg, maxAgg, minAgg, boolAnd, boolOr, arrayAgg, stringAgg, jsonbAgg, jsonbObjectAgg, jsonbBuildObject } from './aggregates.js'
 import { except, exceptAll, intersect, intersectAll, union, unionAll } from '../query/pg-core/index.js'
-import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayOf, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
+import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayOf, row, rowEquals, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
 import { ago, castUuid, castJsonb, castTimestamp, castBoolean, castNumeric, castInteger, castText, nextSequence } from './composed.js'
 import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, concat as jsonbConcat, remove as jsonbRemove } from '../jsonb/query.js'
 import { arrayAny, arrayAll, jsonbElements } from './array-elements.js'
@@ -57,6 +57,8 @@ export const filter = {
   arrayToString,
   arrayAppend,
   arrayOf,
+  row,
+  rowEquals,
   arrayRemove,
   dateTrunc,
   rowNumber,

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
+}