@protobase/server 0.43.1 → 0.44.0

package/dist/admin-options.d.ts

@@ -20,13 +20,21 @@ export type AdminOptions = {
    * `PROTOBASE_SECRET_KEY`. Without either, or with `false`, the app serves neither.
    */
   apiKeys?: ApiKeysOptions | false;
-  /** Applied to every request's transaction with SET LOCAL. Default 15000. */
+  /**
+   * How long a query of an API request may run, set on every request's transaction with SET LOCAL; a query that runs
+   * longer is a 504 that names the request. Default 1000: a query that needs longer wants an index or a simpler filter,
+   * or belongs in a function or job with `longQueries`.
+   */
   statementTimeoutMs?: number;
   /** Reads that filter, sort or count values by a column no index serves. Default mode `reject`. */
   scanGuard?: {
     mode?: ScanGuardMode;
   };
-  /** Runs inside the write transaction after each create, update and delete. */
+  /**
+   * Runs inside the write transaction after each create, update and delete, with that transaction: database work only.
+   * While a hook waits on anything else, such as an HTTP call, the transaction stays open with the row locked; a job the
+   * hook enqueues does such work instead.
+   */
   writeHooks?: PipelineHook[];
   /**
    * The project's roles (from `defineRoles`): an operation without an access rule needs the matching capability. Their
@@ -44,11 +52,16 @@ export type AdminOptions = {
   };
   /** Receives an event for every reveal of a sensitive field. Default: printed to the console, nothing kept. */
   audit?: AuditQueue;
-  /** Called with every error the API turns into a 500, and the request it failed, so the host can report it. */
+  /**
+   * Called with every error the API turns into a 500, and with the problem of every query the database stopped at its
+   * statement timeout and every request that found all database connections busy, and the request it failed, so the
+   * host can report it.
+   */
   onUnhandledError?: (error: unknown, request?: Request) => void;
   /**
-   * Where the app's errors go: the server's 500s and crashes, and the admin app's errors in the browser (see
-   * `ErrorReportingOptions`). Defaults to the DSN the platform passes in `PROTOBASE_SENTRY_DSN`; `false` turns it off.
+   * Where the app's errors go: the server's 500s, stopped queries and crashes, and the admin app's errors in the
+   * browser (see `ErrorReportingOptions`). Defaults to the DSN the platform passes in `PROTOBASE_SENTRY_DSN`; `false`
+   * turns it off.
    */
   errorReporting?: ErrorReportingOptions | false;
   /** The assistant in the admin app's dock: a backend elsewhere or the built-in one (see `AssistantOptions`); `false` turns it off. */

package/dist/app-pool.d.ts

@@ -0,0 +1,47 @@
+//#region src/app-pool.d.ts
+/** How long a query waits for a free connection of the app's pool before it fails with `ConnectionsBusy`. */
+export declare const poolWaitMs = 2000;
+/** How many connections the app's pool opens: `PROTOBASE_DB_CONNECTIONS`, such as its plan's limit, or 10. */
+export declare const readDbConnections: (env: Record<string, string | undefined>) => number;
+type TypeParser = (oid: number, format?: 'text' | 'binary') => unknown;
+/** The settings `appPool` and `longQueryPool` open node-postgres's pool with. */
+export type AppPoolConfig = {
+  connectionString: string;
+  max: number;
+  connectionTimeoutMillis: number;
+  statement_timeout?: number;
+  types: {
+    getTypeParser: TypeParser;
+  };
+};
+type PgPool = {
+  readonly ending: boolean;
+  on(event: 'connect', listener: (client: {
+    on(event: 'error', listener: (error: Error) => void): unknown;
+  }) => void): unknown;
+  on(event: 'error', listener: (error: Error) => void): unknown;
+};
+/** The part of node-postgres `appPool` needs: the app's own `import pg from 'pg'`. */
+export type PgModule<P extends PgPool> = {
+  Pool: new (config: AppPoolConfig) => P;
+  types: {
+    getTypeParser: TypeParser;
+  };
+};
+/**
+ * The app's one pool on the database at `url`, with `max` connections (`PROTOBASE_DB_CONNECTIONS` by default): the
+ * runtime's, which `protobase dev` and `serve` open, and the one the app's own code uses, such as its Better Auth store.
+ * Whoever asks first opens it, and everyone in the process shares it, across a dev server's reloads too, until it ends;
+ * so the app never opens more connections than it may. Date and timestamp (without zone) come back as text, which the
+ * API formats itself, a dropped connection is printed rather than fatal, and a query waits at most `poolWaitMs` for a
+ * free connection.
+ */
+export declare const appPool: <P extends PgPool>(pg: PgModule<P>, url: string, max?: number) => P;
+/**
+ * The runtime's pool of one connection on `url` for the queries of functions and jobs with `longQueries`: it asks for
+ * `statement_timeout` = `longQueryTimeoutMs` when it logs in, which Postgres takes, and the platform's pooler too, since
+ * it tracks that setting (`track_extra_parameters`). A query waits for that connection as long as one may run on it.
+ * It opens its connection on first use, and nobody else shares it.
+ */
+export declare const longQueryPool: <P extends PgPool>(pg: PgModule<P>, url: string) => P;
+//#endregion

package/dist/app-pool.js

@@ -0,0 +1,57 @@
+import { longQueryTimeoutMs } from "./statement-timeout.js";
+import { handleDroppedConnections } from "./dropped-connections.js";
+//#region src/app-pool.ts
+/** How long a query waits for a free connection of the app's pool before it fails with `ConnectionsBusy`. */
+const poolWaitMs = 2e3;
+/** How many connections the app's pool opens: `PROTOBASE_DB_CONNECTIONS`, such as its plan's limit, or 10. */
+const readDbConnections = (env) => {
+	if (!env.PROTOBASE_DB_CONNECTIONS) return 10;
+	const connections = Number(env.PROTOBASE_DB_CONNECTIONS);
+	if (!Number.isInteger(connections) || connections < 1) throw new Error(`PROTOBASE_DB_CONNECTIONS must be a whole number of connections, at least 1, not "${env.PROTOBASE_DB_CONNECTIONS}"`);
+	return connections;
+};
+const textDates = (pg) => ({ getTypeParser: (oid, format) => oid === 1082 || oid === 1114 ? (value) => value : pg.types.getTypeParser(oid, format) });
+const store = globalThis;
+/**
+* The app's one pool on the database at `url`, with `max` connections (`PROTOBASE_DB_CONNECTIONS` by default): the
+* runtime's, which `protobase dev` and `serve` open, and the one the app's own code uses, such as its Better Auth store.
+* Whoever asks first opens it, and everyone in the process shares it, across a dev server's reloads too, until it ends;
+* so the app never opens more connections than it may. Date and timestamp (without zone) come back as text, which the
+* API formats itself, a dropped connection is printed rather than fatal, and a query waits at most `poolWaitMs` for a
+* free connection.
+*/
+const appPool = (pg, url, max = readDbConnections(globalThis.process?.env ?? {})) => {
+	const pools = store.__protobaseAppPools ??= /* @__PURE__ */ new Map();
+	for (const [key, entry] of pools) if (entry.pool.ending) pools.delete(key);
+	const known = pools.get(url);
+	if (known) {
+		if (known.max !== max) throw new Error(`The app's pool on this database is open with ${known.max} connections, so it cannot open with ${max}: give both the same PROTOBASE_DB_CONNECTIONS`);
+		return known.pool;
+	}
+	const pool = handleDroppedConnections(new pg.Pool({
+		connectionString: url,
+		max,
+		connectionTimeoutMillis: poolWaitMs,
+		types: textDates(pg)
+	}));
+	pools.set(url, {
+		pool,
+		max
+	});
+	return pool;
+};
+/**
+* The runtime's pool of one connection on `url` for the queries of functions and jobs with `longQueries`: it asks for
+* `statement_timeout` = `longQueryTimeoutMs` when it logs in, which Postgres takes, and the platform's pooler too, since
+* it tracks that setting (`track_extra_parameters`). A query waits for that connection as long as one may run on it.
+* It opens its connection on first use, and nobody else shares it.
+*/
+const longQueryPool = (pg, url) => handleDroppedConnections(new pg.Pool({
+	connectionString: url,
+	max: 1,
+	connectionTimeoutMillis: longQueryTimeoutMs,
+	statement_timeout: longQueryTimeoutMs,
+	types: textDates(pg)
+}));
+//#endregion
+export { appPool, longQueryPool, poolWaitMs, readDbConnections };

package/dist/background-work.d.ts

@@ -1,9 +1,14 @@
 //#region src/background-work.d.ts
 /**
  * Runs `work` as background work: function calls and jobs, as opposed to page and API requests. A pool that knows,
- * such as the runtime's, keeps a connection free for requests however many connections background work holds.
+ * such as the runtime's, keeps a connection free for requests however many connections background work holds, and
+ * gives work with `longQueries` a connection whose queries may run up to `longQueryTimeoutMs`.
  */
-export declare const runInBackground: <T>(work: () => T) => T;
+export declare const runInBackground: <T>(work: () => T, options?: {
+  longQueries?: boolean;
+}) => T;
 /** Whether the caller runs inside `runInBackground`. */
 export declare const isBackgroundWork: () => boolean;
+/** Whether the caller runs inside `runInBackground` with `longQueries`. */
+export declare const wantsLongQueries: () => boolean;
 //#endregion

package/dist/background-work.js

@@ -3,10 +3,13 @@ import { AsyncLocalStorage } from "node:async_hooks";
 const background = new AsyncLocalStorage();
 /**
 * Runs `work` as background work: function calls and jobs, as opposed to page and API requests. A pool that knows,
-* such as the runtime's, keeps a connection free for requests however many connections background work holds.
+* such as the runtime's, keeps a connection free for requests however many connections background work holds, and
+* gives work with `longQueries` a connection whose queries may run up to `longQueryTimeoutMs`.
 */
-const runInBackground = (work) => background.run(true, work);
+const runInBackground = (work, options = {}) => background.run({ longQueries: options.longQueries === true }, work);
 /** Whether the caller runs inside `runInBackground`. */
-const isBackgroundWork = () => background.getStore() === true;
+const isBackgroundWork = () => background.getStore() !== void 0;
+/** Whether the caller runs inside `runInBackground` with `longQueries`. */
+const wantsLongQueries = () => background.getStore()?.longQueries === true;
 //#endregion
-export { isBackgroundWork, runInBackground };
+export { isBackgroundWork, runInBackground, wantsLongQueries };

package/dist/batch/reorder.js

@@ -46,7 +46,7 @@ const moveAside = async (trx, access, field, keys) => {
 * so that a unique index such as (invoice_id, position) is never violated half way. Everything checks out before any row moves,
 * and with the position's `after` the new order must keep each record below the records it depends on (see `checkRankAfter`).
 */
-const reorderIn = async (trx, deps, access, input) => {
+const reorderIn = async (trx, deps, access, input, removed) => {
 	const { entry, full } = access;
 	requireOperation(access, "update");
 	const field = full.fields[input.field];
@@ -75,7 +75,7 @@ const reorderIn = async (trx, deps, access, input) => {
 	const results = [];
 	for (const [i, key] of input.keys.entries()) {
 		const plan = plans.get(i);
-		results.push(await shown(access, plan ? await applyUpdate(trx, deps, access, key, plan) : current[i]));
+		results.push(await shown(access, plan ? await applyUpdate(trx, deps, access, key, plan, removed) : current[i]));
 	}
 	await checkRankAfter(trx, deps, access, input.field, changing.map((i) => ({
 		key: input.keys[i],

package/dist/batch/run-batch.js

@@ -2,9 +2,10 @@ import { HttpProblem, badRequest, notFound } from "../problem.js";
 import { requestAccess } from "../request-access.js";
 import { actorSettings, wakeDispatch } from "../changes/actor.js";
 import { problemOf } from "../error-handler.js";
+import { scheduleRemovedFiles } from "../files/attach.js";
 import { writeTransaction } from "../transactions.js";
 import { keyOf } from "../write-shared.js";
-import { writeIn } from "../write-pipeline.js";
+import { checkBeforeWrite, writeIn } from "../write-pipeline.js";
 import { resolveData, resolveKey } from "./refs.js";
 import { reorderIn } from "./reorder.js";
 //#region src/batch/run-batch.ts
@@ -25,7 +26,8 @@ const atOperation = (error, index, operation) => {
 };
 /**
 * Runs the operations in order inside ONE transaction, each through the normal write pipeline (validation, access with row
-* filters and record-level rules, tenant, ETags, hooks). Any failure rolls the whole batch back and names the failing operation.
+* filters and record-level rules, tenant, ETags, hooks), after the checks that come before it. Any failure rolls the
+* whole batch back and names the failing operation.
 */
 const runBatch = async (deps, session, operations) => {
 	const refs = operations.flatMap((operation) => operation.op === "create" && operation.ref ? [operation.ref] : []);
@@ -38,6 +40,17 @@ const runBatch = async (deps, session, operations) => {
 		accesses.set(entry.name, access);
 		return access;
 	};
+	for (const [index, operation] of operations.entries()) {
+		if (operation.op !== "create" && operation.op !== "update") continue;
+		await checkBeforeWrite(deps, {
+			resource: operation.resource,
+			operation: operation.op,
+			body: operation.data
+		}).catch((error) => {
+			throw atOperation(error, index, operation);
+		});
+	}
+	const removed = [];
 	const written = await writeTransaction(deps.db, deps.statementTimeoutMs, async (trx) => {
 		const created = /* @__PURE__ */ new Map();
 		const results = [];
@@ -48,7 +61,7 @@ const runBatch = async (deps, session, operations) => {
 				const written = await writeIn(trx, deps, access, {
 					operation: "create",
 					body: resolveData(created, operation.data)
-				});
+				}, removed);
 				if (operation.ref) created.set(operation.ref, {
 					entry,
 					key: keyOf(access, written.record),
@@ -66,7 +79,7 @@ const runBatch = async (deps, session, operations) => {
 					key: resolveKey(created, entry, operation.key),
 					body: resolveData(created, operation.data),
 					ifMatch: operation.etag ?? null
-				});
+				}, removed);
 				results.push({
 					op: "update",
 					resource: entry.name,
@@ -77,7 +90,7 @@ const runBatch = async (deps, session, operations) => {
 					operation: "delete",
 					key: resolveKey(created, entry, operation.key),
 					ifMatch: operation.etag ?? null
-				});
+				}, removed);
 				results.push({
 					op: "delete",
 					resource: entry.name,
@@ -90,7 +103,7 @@ const runBatch = async (deps, session, operations) => {
 					keys,
 					etags: operation.etags ?? {},
 					start: operation.start ?? 1
-				});
+				}, removed);
 				results.push({
 					op: "reorder",
 					resource: entry.name,
@@ -102,6 +115,7 @@ const runBatch = async (deps, session, operations) => {
 		}
 		return results;
 	}, actorSettings(deps, session));
+	await scheduleRemovedFiles(deps, removed);
 	wakeDispatch(deps);
 	return written;
 };

package/dist/connections-busy.d.ts

@@ -0,0 +1,12 @@
+//#region src/connections-busy.d.ts
+/**
+ * Every connection of the app's pool stayed in use for as long as a query may wait for one: queries that run long or
+ * transactions left open hold them.
+ */
+export declare class ConnectionsBusy extends Error {
+  readonly connections: number;
+  readonly waitedMs: number;
+  name: string;
+  constructor(connections: number, waitedMs: number, options?: ErrorOptions);
+}
+//#endregion

package/dist/connections-busy.js

@@ -0,0 +1,20 @@
+import { HttpProblem } from "./problem.js";
+//#region src/connections-busy.ts
+/**
+* Every connection of the app's pool stayed in use for as long as a query may wait for one: queries that run long or
+* transactions left open hold them.
+*/
+var ConnectionsBusy = class extends Error {
+	connections;
+	waitedMs;
+	name = "ConnectionsBusy";
+	constructor(connections, waitedMs, options) {
+		super(`All ${connections} database connections stayed busy for ${waitedMs / 1e3} s`, options);
+		this.connections = connections;
+		this.waitedMs = waitedMs;
+	}
+};
+/** The 503 of `subject` (such as `GET /api/v1/tasks`), which found every connection busy and so did not run. */
+const connectionsBusyProblem = (error, subject) => new HttpProblem(503, "connections-busy", "Service Unavailable", `${subject} waited ${error.waitedMs / 1e3} s for one of the app's ${error.connections} database connections, which all stayed busy, so it did not run. Queries that run long or transactions left open hold them.`, {}, { "Retry-After": "1" });
+//#endregion
+export { ConnectionsBusy, connectionsBusyProblem };

package/dist/create-admin.js

@@ -4,6 +4,7 @@ import { unauthorized } from "./problem.js";
 import { fillHook } from "./ai/fill-hook.js";
 import { isCaptured } from "./changes/capture-sql.js";
 import { wakeDispatch } from "./changes/actor.js";
+import "./statement-timeout.js";
 import { createErrorHandler } from "./error-handler.js";
 import { assistantRecords } from "./assistant/records.js";
 import { fillJob } from "./ai/fill-job.js";
@@ -49,7 +50,7 @@ import { callerRecords } from "./functions/records.js";
 import { toApiFunction } from "./functions/define-function.js";
 import { createWebhooks } from "./webhooks/webhooks.js";
 import { webhookTable } from "./webhooks/table/webhook-table.js";
-import { subscriptionWriteCheck } from "./webhooks/table/validate-hook.js";
+import { subscriptionUrlCheck, subscriptionWriteCheck } from "./webhooks/table/validate-hook.js";
 import { visitorsBrowse, withAnonymous } from "./anonymous.js";
 import { checkBottomBars, checkShell } from "./check-shell.js";
 import { checkOwnerFields } from "./check-owners.js";
@@ -181,14 +182,16 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 		bottomBars: bottomBarModels,
 		basePath,
 		systemPath,
-		statementTimeoutMs: options.statementTimeoutMs ?? 15e3,
+		statementTimeoutMs: options.statementTimeoutMs ?? 1e3,
 		guard: createScanGuard(db, options.scanGuard),
 		hooks: [
 			...options.writeHooks ?? [],
-			...table ? [subscriptionWriteCheck(registry.entries.map((entry) => entry.model), table.checkUrl)] : [],
+			...table ? [subscriptionWriteCheck(registry.entries.map((entry) => entry.model))] : [],
 			...fill ? [fillHook(() => deps, fill)] : []
 		],
+		writeChecks: table?.checkUrl ? [subscriptionUrlCheck(table.checkUrl)] : [],
 		audit: options.audit ?? consoleAuditQueue(),
+		report: options.onUnhandledError ?? ((error) => console.error(error)),
 		accessOptions: {
 			...options.roles && { roles: options.roles },
 			...options.defaultAccess && { defaultAccess: options.defaultAccess }
@@ -220,7 +223,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 	};
 	const appName = auth?.appName ?? readAppName(globalThis.process?.env ?? {}) ?? "Protobase";
 	const meta = createMeta(deps, appName, icons?.favicon ? faviconPath : void 0);
-	const onError = createErrorHandler(options.onUnhandledError);
+	const onError = createErrorHandler(options.onUnhandledError, deps.statementTimeoutMs);
 	const guarded = (routes, caller = authenticate) => {
 		const app = new Hono();
 		app.onError(onError);
@@ -296,7 +299,7 @@ const createAdmin = ({ resources: appResources, views: appViews = [], pages = []
 			report: options.onUnhandledError
 		}));
 	}
-	const report = options.onUnhandledError ?? ((error) => console.error(error));
+	const { report } = deps;
 	if (auth?.mcp && options.mcp === false) closedMcpRoutes(app, auth.mcp.path);
 	else if (auth?.mcp && mcpAuthenticate) {
 		const writes = options.mcp !== false && options.mcp?.writes || false;

package/dist/deps.d.ts

@@ -1,4 +1,4 @@
-import { AuditQueue, PipelineHook } from "./types.js";
+import { AuditQueue, PipelineHook, WriteCheck } from "./types.js";
 import { CommentUsers } from "./comments/comment-users.js";
 import { ErrorReportingSettings } from "./error-reporting/error-reporting-settings.js";
 import { mentionJob } from "./comments/mention-job.js";
@@ -30,9 +30,13 @@ export type Deps = {
   statementTimeoutMs: number;
   guard: ScanGuard;
   hooks: readonly PipelineHook[];
+  /** Run on a create's or update's body before its transaction opens (see `WriteCheck`). */
+  writeChecks: readonly WriteCheck[];
   accessOptions: ResolveOptions;
   /** Where reveals of sensitive fields are published. */
   audit: AuditQueue;
+  /** Gets the errors of work that runs after a request's response is decided, such as a committed write's file cleanup. */
+  report: (error: unknown) => void;
   /** Whether list items of a resource carry their permissions. */
   rowPermissions: (resource: string) => boolean;
   /** The URL of the assistant backend that `/meta` names to callers who may use it: another origin's, or the built-in one's path. */

package/dist/error-handler.js

@@ -1,4 +1,6 @@
 import { HttpProblem, problemResponse } from "./problem.js";
+import { ConnectionsBusy, connectionsBusyProblem } from "./connections-busy.js";
+import { StatementTimeout } from "./statement-timeout.js";
 import { HTTPException } from "hono/http-exception";
 import { QueryError } from "@protobase/query";
 //#region src/error-handler.ts
@@ -25,7 +27,7 @@ const queryProblem = (error) => {
 const isDatabaseError = (error) => error instanceof Error && /^[0-9A-Z]{5}$/.test(String(error.code));
 const databaseProblem = (error) => {
 	if (error.code === "25006") return new HttpProblem(503, "read-only", "Service Unavailable", "The app is read-only while it is being updated", {}, { "Retry-After": "5" });
-	if (error.code === "57014") return new HttpProblem(504, "statement-timeout", "Gateway Timeout", "The query exceeded the statement timeout");
+	if (error.code === "57014") return new HttpProblem(504, "statement-timeout", "Gateway Timeout", "A query ran longer than its statement timeout, so the database stopped it");
 	if (error.code === "23505") return new HttpProblem(409, "conflict", "Conflict", "A record with the same unique value already exists");
 	if (error.code === "23503") return new HttpProblem(409, "conflict", "Conflict", "The record points at, or is pointed at by, another record");
 	if (error.code === "40P01") return new HttpProblem(409, "conflict", "Conflict", "The record was written at the same time as another; send it again");
@@ -34,10 +36,29 @@ const databaseProblem = (error) => {
 	if (error.code.startsWith("22")) return new HttpProblem(400, "invalid-value", "Bad Request", "A value has the wrong format for its column");
 };
 /** The problem an error stands for, when it is one the API knows how to report; unknown errors give `undefined`. */
-const problemOf = (error) => error instanceof HttpProblem ? error : error instanceof QueryError ? queryProblem(error) : error instanceof HTTPException ? new HttpProblem(error.status, "http-error", titles[error.status] ?? "Error", error.message) : error instanceof SyntaxError ? new HttpProblem(400, "malformed-json", "Bad Request", "The request body is not valid JSON") : isDatabaseError(error) ? databaseProblem(error) : void 0;
-/** The single place where errors become responses: RFC 9457 problems, never raw error messages for unexpected failures. */
-const createErrorHandler = (onUnhandledError) => (error, c) => {
+const problemOf = (error) => error instanceof HttpProblem ? error : error instanceof QueryError ? queryProblem(error) : error instanceof HTTPException ? new HttpProblem(error.status, "http-error", titles[error.status] ?? "Error", error.message) : error instanceof SyntaxError ? new HttpProblem(400, "malformed-json", "Bad Request", "The request body is not valid JSON") : isDatabaseError(error) ? databaseProblem(error) : error instanceof ConnectionsBusy ? connectionsBusyProblem(error, "The query") : void 0;
+const namedTimeout = (problem, c, statementTimeoutMs) => problem instanceof StatementTimeout ? problem : new StatementTimeout(`${c.req.method} ${c.req.path}`, statementTimeoutMs === void 0 ? { kind: "database" } : {
+	kind: "request",
+	ms: statementTimeoutMs
+}, problem.extras);
+/**
+* The single place where errors become responses: RFC 9457 problems, never raw error messages for unexpected failures.
+* Unexpected failures go to `onUnhandledError` as well, and so do a query stopped at its statement timeout
+* (`statementTimeoutMs`, the requests' own, when they set one) and a request that found every database connection
+* busy, as the problem that names the request.
+*/
+const createErrorHandler = (onUnhandledError, statementTimeoutMs) => (error, c) => {
+	if (error instanceof ConnectionsBusy) {
+		const named = connectionsBusyProblem(error, `${c.req.method} ${c.req.path}`);
+		onUnhandledError?.(named, c.req.raw);
+		return problemResponse(named, c.req.path);
+	}
 	const known = problemOf(error);
+	if (known?.slug === "statement-timeout") {
+		const named = namedTimeout(known, c, statementTimeoutMs);
+		onUnhandledError?.(named, c.req.raw);
+		return problemResponse(named, c.req.path);
+	}
 	if (known) return problemResponse(known, c.req.path);
 	onUnhandledError?.(error, c.req.raw);
 	return problemResponse(new HttpProblem(500, "internal-error", titles[500], "The server failed to handle the request"), c.req.path);

package/dist/files/attach.js

@@ -74,16 +74,16 @@ const attachFiles = async (access, values, current) => {
 	return result;
 };
 /**
-* Schedules the delete of every file a write took out of its row, with its variants: a replaced or cleared value, or all
-* of a hard-deleted row's files, each due after its provider's retention. It runs inside the write transaction, before the commit: if
-* the write rolls back, the file is still referenced when the entry is due, and stays.
+* The deletes of every file a write took out of its row, with its variants: a replaced or cleared value, or all of a
+* hard-deleted row's files, each due after its provider's retention. The write schedules them once it commits
+* (`scheduleRemovedFiles`).
 */
-const scheduleRemovedFiles = async (access, operation, before, after) => {
+const removedFiles = (access, operation, before, after) => {
 	const files = access.deps.files;
-	if (!files || !before || operation === "create" || operation === "undelete") return;
-	if (operation === "delete" && access.full.softDelete) return;
+	if (!files || !before || operation === "create" || operation === "undelete") return [];
+	if (operation === "delete" && access.full.softDelete) return [];
 	const now = Date.now();
-	const removed = fileFields(access).flatMap((field) => {
+	return fileFields(access).flatMap((field) => {
 		const old = before[field.name];
 		if (typeof old !== "string") return [];
 		const next = after?.[field.name];
@@ -98,7 +98,15 @@ const scheduleRemovedFiles = async (access, operation, before, after) => {
 			...variants.length > 0 && { variants }
 		}];
 	});
-	if (removed.length > 0) await files.schedule.add(removed);
+};
+/**
+* Schedules the deletes of the files a committed write took out of its rows. After the commit, so the transaction never
+* waits on the storage; a failure leaves the files in it, never a row that points at a deleted one, and is reported,
+* since the write itself stands.
+*/
+const scheduleRemovedFiles = async (deps, removed) => {
+	if (!deps.files || removed.length === 0) return;
+	await deps.files.schedule.add(removed).catch(deps.report);
 };
 //#endregion
-export { attachFiles, scheduleRemovedFiles, ticketScope };
+export { attachFiles, removedFiles, scheduleRemovedFiles, ticketScope };

package/dist/files/download.js

@@ -1,8 +1,8 @@
 import { HttpProblem, forbidden, notFound } from "../problem.js";
-import { readTransaction } from "../transactions.js";
-import { fetchRecord } from "../records.js";
 import { contentDisposition, downloadName, servedType } from "./media-types.js";
 import { isFilePath, parseUri, tenantSegment, variantPaths } from "./uri.js";
+import { readTransaction } from "../transactions.js";
+import { fetchRecord } from "../records.js";
 import { downloadExpiry, readDownloadUrl } from "./download-url.js";
 import { decodeKeyText } from "../key.js";
 //#region src/files/download.ts

package/dist/functions/define-function.d.ts

@@ -56,6 +56,11 @@ export type CorsOptions = {
 type SharedOptions = {
   /** Answers CORS preflights before authentication and adds the CORS headers to every response, problems included. */
   cors?: CorsOptions;
+  /**
+   * Its queries through `db` may run up to 30 seconds instead of the database's own limit, on a connection kept for
+   * such work: for imports, reports and other bulk work. Its `records` keep the API's limit.
+   */
+  longQueries?: boolean;
   /**
    * Also answers at `/api/sb/functions/v1/<name>`, as Supabase's `verify_jwt` does, where the app's publishable key alone
    * admits a caller. For functions moved from Supabase; not together with `roles` or `capability`.

package/dist/functions/routes.js

@@ -1,4 +1,5 @@
 import { forbidden, notFound } from "../problem.js";
+import { namingTimeouts } from "../statement-timeout.js";
 import { invokeFunction } from "./define-function.js";
 import { runInBackground } from "../background-work.js";
 import { socketAcceptor } from "./accept-socket.js";
@@ -32,7 +33,10 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 			records: records(session)
 		};
 	};
-	const call = (work) => work().finally(wake);
+	const call = (fn, subject, work) => {
+		const { longQueries } = fn.options;
+		return runInBackground(() => namingTimeouts(subject, { kind: longQueries ? "long" : "database" }, work).finally(wake), { longQueries });
+	};
 	const recheckCaller = async (name, gate, request, first) => {
 		const again = await upgradeAuthenticate(request);
 		requireGate(name, gate, again);
@@ -43,7 +47,7 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 		const { options } = fn;
 		const gate = functionGate(name, options, access);
 		if (options.cors) app.use(`/${name}/*`, cors(options.cors));
-		app.all(`/${name}/*`, (c) => runInBackground(() => call(async () => {
+		app.all(`/${name}/*`, (c) => call(fn, `${c.req.method} ${c.req.path}`, async () => {
 			const request = relativeRequest(c.req.raw, prefix);
 			if (options.public) {
 				let caller;
@@ -83,7 +87,7 @@ const functionRoutes = ({ basePath, functions, authenticate, access, db, records
 				acceptWebSocket: acceptor.accept
 			};
 			return acceptor.answer(name, await invokeFunction(name, fn, request, context));
-		})));
+		}));
 	}
 	app.all("/*", (c) => {
 		throw notFound(`There is no function at ${c.req.path}`);

package/dist/functions/supabase-routes.js

@@ -1,4 +1,5 @@
 import { notFound, unauthorized } from "../problem.js";
+import { namingTimeouts } from "../statement-timeout.js";
 import { supabaseFunctionsPath } from "../supabase-paths.js";
 import { invokeFunction } from "./define-function.js";
 import { runInBackground } from "../background-work.js";
@@ -30,7 +31,8 @@ const supabaseFunctionRoutes = ({ functions, db, keys, caller, onError }) => {
 		const gated = roles !== void 0 ? "roles" : capability !== void 0 ? "a capability" : void 0;
 		if (gated) throw new Error(`The function "${name}" has supabase: true and ${gated}, which /api/sb/functions/v1 cannot check: drop one`);
 		if (options.cors) app.use(`/${name}/*`, cors(options.cors));
-		app.all(`/${name}/*`, (c) => runInBackground(async () => {
+		const limit = { kind: options.longQueries ? "long" : "database" };
+		app.all(`/${name}/*`, (c) => runInBackground(() => namingTimeouts(`${c.req.method} ${c.req.path}`, limit, async () => {
 			const request = relativeRequest(c.req.raw, supabaseFunctionsPath);
 			if (options.public || c.req.method === "OPTIONS") {
 				let resolved;
@@ -47,7 +49,7 @@ const supabaseFunctionRoutes = ({ functions, db, keys, caller, onError }) => {
 				db,
 				caller: async () => resolved
 			});
-		}));
+		}), { longQueries: options.longQueries }));
 	}
 	app.all("/*", (c) => {
 		throw notFound(`There is no function at ${c.req.path}`);

package/dist/index.d.ts

@@ -51,7 +51,10 @@ import { RuntimeOptions, runtimeUrl, runtimeVariable, seesRuntime } from "./runt
 import { AdminOptions } from "./admin-options.js";
 import { CreateAdminInput, createAdmin } from "./create-admin.js";
 import { handleDroppedConnections } from "./dropped-connections.js";
-import { isBackgroundWork, runInBackground } from "./background-work.js";
+import { AppPoolConfig, PgModule, appPool, longQueryPool, poolWaitMs, readDbConnections } from "./app-pool.js";
+import { ConnectionsBusy } from "./connections-busy.js";
+import { isBackgroundWork, runInBackground, wantsLongQueries } from "./background-work.js";
+import { longQueryTimeoutMs } from "./statement-timeout.js";
 import { checkViewQueries } from "./check-view-queries.js";
 import { ProjectConfig, defineConfig, mergeConfig } from "./project-config.js";
 import { consoleAuditQueue } from "./audit/console-queue.js";
@@ -133,4 +136,4 @@ import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.
 import { MobileRelease, ReleaseFile, ServedReleaseFile, composeRelease, releaseManifest } from "./mobile-release/release.js";
 import { MobileReleaseAppInput, OfferedRelease, mobileReleaseApp } from "./mobile-release/release-app.js";
 import { mobileSigningKeyVariable, readSigningKey } from "./mobile-release/signing-key.js";
-export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApiKeys, type ApiKeysOptions, type AppIcons, type AppIdentity, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentUsers, type Completion, type CompletionOptions, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryOptions, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReadableResources, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthAuthenticator, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkQueryRunner, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, mergeConfig, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, processor, queryRunnerMigration, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, sessionOf, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, variantPath, verifySignature, verifyStandardWebhook, waitUntil, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { type Admin, type AdminAuth, type AdminOptions, type ApiFunction, type ApiKeys, type ApiKeysOptions, type AppIcons, type AppIdentity, type AppPoolConfig, type ApplyOptions, type ApplyResult, type ApprovalAnswer, type ApprovalRequest, type AssistantBackend, type AssistantOptions, type AssistantSettings, type AssistantTool, type AuditEvent, type AuditQueue, type Authenticator, type BatchOperation, type BatchResult, type BetterAuthAuthenticator, type BetterAuthAuthenticatorOptions, type Caller, type CallerOptions, type CapturedRow, type CascadingKey, type ChatMessage, type ChatTextPart, type CheckAiInput, type CleanupEntry, type CleanupReport, type CleanupSchedule, type CoalescedChange, type CommentItem, type CommentUsers, type Completion, type CompletionOptions, ConnectionsBusy, type Conversation, type ConversationRecord, type ConversationStore, type ConversationsOptions, type CorsOptions, type CorsOrigins, type CreateAdminInput, type CreateAuthOptions, type DrainResult, type EmailComponent, type EmailOptions, type EmailTemplate, type EncryptionStatus, type EncryptionTools, type EncryptionToolsInput, type EnqueueOptions, type ErrorReporter, type ErrorReportingOptions, type ErrorReportingSettings, type EventData, type EventsOptions, FatalJobError, type FieldApplied, type FieldStatus, type FileCleanupInput, type FileLimits, type FileObject, type FileProvider, type FileRef, type FileStore, type FileVariantObject, type FilesOptions, type FunctionApp, type FunctionCaller, type FunctionContext, type FunctionEnv, type FunctionHandler, type FunctionOptions, type FunctionRecords, type FunctionSocket, type FunctionSource, type HistoryOptions, HttpProblem, type IssueTokenOptions, type JobContext, type JobDefinition, type JobOptions, type JobsRuntime, type JwtOptions, type JwtVerifyOptions, type KeyFunctionContext, type LinkedAccount, type ListParams, type LocalFilesOptions, type MailMessage, type Mailer, type MapLayer, type MapOptions, type MapSettings, type McpGateInput, type McpHandlerInput, type McpRoutesInput, type McpServerInput, type McpToolsInput, type McpWrites, type MemberInput, MissingCredentials, type MobileConfig, type MobileRelease, type MobileReleaseAppInput, ModelError, type ModelSettings, type NewOrganization, type NewUser, type OfferedRelease, type OperatorProvider, type OrganizationRole, type OrganizationsOptions, type PgModule, type PipelineHook, type PlatformSignIn, type PluginOption, type PluginRef, type PngIcon, type ProjectConfig, type ProtectedFunctionOptions, type PublicFunctionContext, type PublicFunctionEnv, type PublicFunctionHandler, type PublicFunctionOptions, type QueryOptions, type QueryResult, type ReadableResources, type ReasoningDetail, type ReasoningEffort, type RebindOption, type RecordKeyInput, type RecordPage, type ReleaseFile, type RenderedEmail, type ResourceChange, type ResourceSource, type RoleDefinition, type RolesInput, type RunContext, type RuntimeOptions, type S3Bucket, type S3FilesOptions, type S3ListPage, type S3Object, type ScanGuardMode, type ScheduledDelete, type ServedReleaseFile, type Session, type SessionOrganization, type Sharp, type SignInPolicy, type SignInRule, type SignatureOptions, type SocketEvents, type SourceOption, type SourceRef, type StaffAccessRule, type StaffSignIn, type StandardSchema, type StandardWebhookOptions, type StartJobsOptions, type StoreFileInput, type StoredMember, type StoredObject, type StoredOrganization, type StoredUser, type StrayValues, type SubscriptionDefinition, type SubscriptionEvent, type SubscriptionOptions, type TenantValue, type ToolAnnotations, type ToolCall, type ToolContext, type ToolRecord, type ToolRecords, type ToolSpec, type TrustedApp, type TurnOptions, type UnreadableEntry, type User, type UserCreatedHook, type ViewSource, type WebhooksOptions, type WidgetOptions, type WriteEvent, type WriteOperation, type WriteRecordToolsInput, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appPool, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthAuthenticator, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkQueryRunner, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, localFiles, longQueryPool, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, mergeConfig, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, processor, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, sessionOf, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/index.js

@@ -1,6 +1,8 @@
 import { HttpProblem, MissingCredentials, badRequest, forbidden, notFound, unauthorized } from "./problem.js";
 import { checkJobsSchema, jobsSchema, jobsSchemaMigration } from "./jobs/schema.js";
 import { isCaptured } from "./changes/capture-sql.js";
+import { ConnectionsBusy } from "./connections-busy.js";
+import { longQueryTimeoutMs } from "./statement-timeout.js";
 import { formatUri, variantPath } from "./files/uri.js";
 import { isSchedule } from "./jobs/schedule.js";
 import { defineJob, isJobDefinition, jobDefinitions } from "./jobs/define-job.js";
@@ -60,7 +62,7 @@ import { limitedFileStore, storeUsage } from "./files/limits.js";
 import { localFileStore, localFiles } from "./files/local-files.js";
 import { s3FileStore, s3Files } from "./files/s3-files.js";
 import { storageProvider } from "./files/storage-provider.js";
-import { isBackgroundWork, runInBackground } from "./background-work.js";
+import { isBackgroundWork, runInBackground, wantsLongQueries } from "./background-work.js";
 import { capSocketMessages, honorSocketMessageCaps, socketMessageCapOf } from "./functions/socket-message-cap.js";
 import { mapSettings, mapStyleUrl, mapStyleVariable } from "./maps/map-settings.js";
 import { beforeSignInPluginsVariable, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable } from "./plugins/plugin-settings.js";
@@ -70,6 +72,7 @@ import { renderVariant, thumbHash } from "./files/images.js";
 import { pngIcons } from "./web-app/app-icons.js";
 import { createAdmin } from "./create-admin.js";
 import { handleDroppedConnections } from "./dropped-connections.js";
+import { appPool, longQueryPool, poolWaitMs, readDbConnections } from "./app-pool.js";
 import { configExports } from "./resource-source.js";
 import { checkViewQueries } from "./check-view-queries.js";
 import { defineConfig, mergeConfig } from "./project-config.js";
@@ -100,4 +103,4 @@ import { jobsDrainApp } from "./jobs/drain-route.js";
 import { composeRelease, releaseManifest } from "./mobile-release/release.js";
 import { mobileReleaseApp } from "./mobile-release/release-app.js";
 import { mobileSigningKeyVariable, readSigningKey } from "./mobile-release/signing-key.js";
-export { FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthAuthenticator, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkQueryRunner, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, localFiles, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, mergeConfig, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, processor, queryRunnerMigration, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, sessionOf, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, variantPath, verifySignature, verifyStandardWebhook, waitUntil, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };
+export { ConnectionsBusy, FatalJobError, HttpProblem, MissingCredentials, ModelError, addAppRoleToOwners, addMember, apiKeyCaller, apiKeySettings, apiKeyVariables, appPool, aspectRatio, assistantProtocolRoutes, assistantRoles, assistantSettings, assistantVariables, authSchemaMigration, authStoreTables, backgroundSettled, badRequest, batchWriteTool, beforeSignInPluginsVariable, betterAuthAuthenticator, betterAuthTokens, capSocketMessages, changesMigration, checkAi, checkAuthSchema, checkChanges, checkComments, checkComputed, checkJobsSchema, checkQueryRunner, checkSourceNames, checkViewQueries, checkWebhooksSchema, coalesce, commentsMigration, composeRelease, computedMigration, configExports, consoleAuditQueue, conversationKey, createAdmin, createAuth, createConversations, createEncryptionTools, createFileCleanup, createOrganization, createRecordTool, createUser, defaultAppName, defaultSignInPolicy, defineConfig, defineEmail, defineFunction, defineJob, defineTool, deleteRecordTool, deleteUser, errorReportingSettings, errorReportingVariable, eventMatcher, fileConversationStore, fileSize, fileType, forbidden, formatUri, functionApp, getRecordTool, goTruePath, handleDroppedConnections, hasUsers, honorSocketMessageCaps, imageSize, isBackgroundWork, isCaptured, isJobDefinition, isOAuthWellKnownPath, isSchedule, issueToken, jobDefinitions, jobsDrainApp, jobsSchema, jobsSchemaMigration, jwtAuthenticator, jwtVerifier, limitedFileStore, listOrganizations, listRecordsTool, listResourcesTool, listUsers, localFileStore, localFiles, longQueryPool, longQueryTimeoutMs, mapSettings, mapStyleUrl, mapStyleVariable, maxTokenTtlSeconds, maxWidgetPropsBytes, mcpGate, mcpHandler, mcpRoutes, mcpServer, mcpToolContext, mcpTools, mergeConfig, migrationCommand, mobileReleaseApp, mobileSigningKeyVariable, newWebhookSecret, normalizeRoles, notFound, oauthWellKnownPaths, objectKey, parseColumns, parseRoles, passwordLength, pluginOptions, pluginsBeforeSignIn, pluginsFor, pluginsVariable, pngIcons, poolWaitMs, processor, queryRunnerMigration, readDbConnections, readJson, readOnlyQueryTool, readOperatorSettings, readOutbox, readPlatformSignIn, readRecordTools, readSigningKey, readWriteQueryTool, readableResources, realtimeLimits, recordOf, releaseManifest, removeMember, renderVariant, requestApproval, requireEnv, resourceChange, roleChoices, runInBackground, runReadOnlyQuery, runReadWriteQuery, runTurn, runtimeUrl, runtimeVariable, s3FileStore, s3Files, seesAssistant, seesRuntime, sessionOf, setMemberRoles, setUserBanned, setUserRole, signInPolicyMethods, socketMessageCapOf, sourceOptions, sourcesFor, sourcesVariable, startErrorReporting, startJobs, storageCleanupSchedule, storageProvider, storeFile, storeUsage, streamChatCompletion, subscription, supabasePath, thumbHash, unauthorized, updateRecordTool, variantPath, verifySignature, verifyStandardWebhook, waitUntil, wantsLongQueries, webauthnPath, webhooks, webhooksMigration, widget, withCacheBreakpoints, withTrustedApps, writeRecordTools };

package/dist/jobs/job-types.d.ts

@@ -31,6 +31,11 @@ export type JobOptions<Payload> = {
   maxRetryDelay?: number | string;
   /** How long one try may run before it counts as failed. Default `15 minutes`. */
   timeout?: number | string;
+  /**
+   * Its queries through `db` may run up to 30 seconds instead of the database's own limit, on a connection kept for
+   * such work: for imports, backfills, large deletes and other bulk work.
+   */
+  longQueries?: boolean;
   /** Jobs of this name running at once in each worker process. Default 1. */
   concurrency?: number;
   /**

package/dist/jobs/run-job.js

@@ -1,3 +1,4 @@
+import { isStatementTimeout, statementTimeoutDetail } from "../statement-timeout.js";
 //#region src/jobs/run-job.ts
 /** Thrown from a job's `run`, it fails the job now: the attempts it has left are not used. */
 var FatalJobError = class extends Error {
@@ -44,6 +45,10 @@ const errorOutput = (error) => error instanceof Error ? {
 	message: error.message,
 	...error.stack && { stack: error.stack }
 } : { message: String(error) };
+const namedTimeout = (definition, error) => {
+	if (!isStatementTimeout(error)) return error;
+	return new Error(statementTimeoutDetail(`Job "${definition.name}"`, { kind: definition.options.longQueries ? "long" : "database" }), { cause: error });
+};
 /**
 * One try of one job: completed when `run` returns, failed (to be retried while attempts are left) when it throws, and
 * failed for good on a `FatalJobError` or an invalid payload.
@@ -71,7 +76,7 @@ const runJob = async (definition, job, db, mail) => {
 		return {
 			id: job.id,
 			status: error instanceof FatalJobError ? "deadletter" : "failed",
-			output: errorOutput(error)
+			output: errorOutput(namedTimeout(definition, error))
 		};
 	}
 };

package/dist/jobs/runtime.js

@@ -52,11 +52,13 @@ const startJobs = async ({ db, jobs, work = true, pollSeconds = 2, shutdownSecon
 		const running = workers.get(definition.name);
 		if (running?.concurrency === concurrency) return;
 		if (running) await boss.offWork(definition.name);
-		const id = await boss.work(definition.name, workOptions(concurrency, pollSeconds), async ([job]) => runInBackground(async () => {
+		const id = await boss.work(definition.name, workOptions(concurrency, pollSeconds), async ([job]) => {
 			const current = definitions.get(definition.name) ?? definition;
-			if (current.options.schedule !== void 0 && job.singletonKey === "protobase.schedule") await schedules.following(current, job.startAfter);
-			return [await runJob(current, job, db, mail)];
-		}));
+			return runInBackground(async () => {
+				if (current.options.schedule !== void 0 && job.singletonKey === "protobase.schedule") await schedules.following(current, job.startAfter);
+				return [await runJob(current, job, db, mail)];
+			}, { longQueries: current.options.longQueries });
+		});
 		workers.set(definition.name, {
 			id,
 			concurrency

package/dist/mcp/mcp-server.js

@@ -1,8 +1,17 @@
+import { isStatementTimeout } from "../statement-timeout.js";
 import { checkedTools } from "../assistant/checked-tools.js";
 import { ApprovalNeeded, approvalAsked, approvedUnasked, mcpApproval, writesUnasked } from "./mcp-approval.js";
 import { CLIENT_CAPABILITIES_META_KEY, McpServer, fromJsonSchema } from "@modelcontextprotocol/server";
 //#region src/mcp/mcp-server.ts
 const capabilitiesOf = (envelope) => envelope?.[CLIENT_CAPABILITIES_META_KEY];
+const inputSchemas = /* @__PURE__ */ new WeakMap();
+const inputSchemaOf = (parameters) => {
+	const known = inputSchemas.get(parameters);
+	if (known) return known;
+	const schema = fromJsonSchema(parameters);
+	inputSchemas.set(parameters, schema);
+	return schema;
+};
 const failed = {
 	content: [{
 		type: "text",
@@ -10,6 +19,13 @@ const failed = {
 	}],
 	isError: true
 };
+const stopped = (tool) => ({
+	content: [{
+		type: "text",
+		text: `${tool} ran a query longer than its statement timeout, so the database stopped it. Ask for less, such as with a narrower filter or fewer fields.`
+	}],
+	isError: true
+});
 /**
 * An MCP server offering `tools` as MCP tools, each with its JSON Schema, its hints, and the text it returns. A tool
 * that asks for approval makes the call ask the client's user, and runs again from the start with their answer; for a
@@ -21,7 +37,7 @@ const mcpServer = ({ info, tools, context, report, rolesWithoutApproval = [] })
 	for (const tool of checkedTools(tools)) {
 		const config = {
 			description: tool.description,
-			inputSchema: fromJsonSchema(tool.parameters),
+			inputSchema: inputSchemaOf(tool.parameters),
 			...tool.annotations && { annotations: tool.annotations }
 		};
 		server.registerTool(tool.name, config, async (args, ctx) => {
@@ -36,7 +52,7 @@ const mcpServer = ({ info, tools, context, report, rolesWithoutApproval = [] })
 			} catch (error) {
 				if (error instanceof ApprovalNeeded) return approvalAsked(error.request, capabilitiesOf(ctx.mcpReq.envelope));
 				report(error);
-				return failed;
+				return isStatementTimeout(error) ? stopped(tool.name) : failed;
 			}
 		});
 	}

package/dist/mcp/mcp-tools.js

@@ -9,10 +9,15 @@ import { batchWriteTool } from "../assistant/batch-write-tool.js";
 * is on and the caller sees the assistant.
 */
 const writeTools = (input) => [...writeRecordTools(input), batchWriteTool(input)];
-const mcpTools = ({ db, sql, writes }) => (session) => [
-	...readRecordTools(),
-	...writes === false ? [] : writeTools(writes === true || !writes.resources ? {} : { resources: writes.resources }),
-	...sql && seesAssistant(session.user.roles) ? [readOnlyQueryTool(db)] : []
-];
+const mcpTools = ({ db, sql, writes }) => {
+	const read = readRecordTools();
+	const write = writes === false ? [] : writeTools(writes === true || !writes.resources ? {} : { resources: writes.resources });
+	const query = sql ? [readOnlyQueryTool(db)] : [];
+	return (session) => [
+		...read,
+		...write,
+		...seesAssistant(session.user.roles) ? query : []
+	];
+};
 //#endregion
 export { mcpTools };

package/dist/package.js

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "0.43.1";
+var version = "0.44.0";
 //#endregion
 export { version };

package/dist/rest/rest-routes.js

@@ -1,4 +1,5 @@
 import { HttpProblem } from "../problem.js";
+import { StatementTimeout, isStatementTimeout } from "../statement-timeout.js";
 import { foreignKeyCache } from "./foreign-keys.js";
 import { restError, restErrorOf } from "./rest-error.js";
 import { errorResponse } from "./respond.js";
@@ -16,6 +17,14 @@ const restRoutes = ({ deps, caller, report }) => {
 	const app = new Hono();
 	app.onError((error, c) => {
 		const known = restErrorOf(error, c.get("caller")?.role === "anon");
+		if (known && isStatementTimeout(error)) {
+			const named = new StatementTimeout(`${c.req.method} ${c.req.path}`, {
+				kind: "request",
+				ms: deps.statementTimeoutMs
+			});
+			report?.(named, c.req.raw);
+			return errorResponse(restError(known.status, known.body.code, known.body.message, known.body.details, named.detail));
+		}
 		if (known) return errorResponse(known);
 		if (error instanceof HttpProblem) return errorResponse(restError(error.status, error.status === 401 ? "PGRST301" : "PGRST000", error.detail).withHeaders(error.headers));
 		report?.(error, c.req.raw);

package/dist/statement-timeout.d.ts

@@ -0,0 +1,7 @@
+//#region src/statement-timeout.d.ts
+/**
+ * How long a query of a function or job with `longQueries: true` may run: the most any query of an app may, which the
+ * platform's pooler enforces as well.
+ */
+export declare const longQueryTimeoutMs = 30000;
+//#endregion

package/dist/statement-timeout.js

@@ -0,0 +1,34 @@
+import { HttpProblem } from "./problem.js";
+//#region src/statement-timeout.ts
+/** How long a query of an API request may run unless the app sets `statementTimeoutMs`. */
+const defaultStatementTimeoutMs = 1e3;
+/**
+* How long a query of a function or job with `longQueries: true` may run: the most any query of an app may, which the
+* platform's pooler enforces as well.
+*/
+const longQueryTimeoutMs = 3e4;
+/** SQLSTATE 57014: Postgres stopped a statement at its `statement_timeout`. */
+const isStatementTimeout = (error) => error instanceof Error && error.code === "57014";
+const seconds = (ms) => `${ms / 1e3} s`;
+/** What ran too long (`subject`, such as `GET /api/v1/tasks`), the limit, and the ways out. */
+const statementTimeoutDetail = (subject, limit) => {
+	if (limit.kind === "long") return `${subject} ran a query longer than ${seconds(longQueryTimeoutMs)}, the most a query may run, so the database stopped it. Make the query faster, or split the work into smaller steps, such as a job per batch.`;
+	return `${subject} ran a query longer than ${limit.kind === "request" ? seconds(limit.ms) : "the database's statement timeout"}, so the database stopped it. Make the query faster, such as with an index or a narrower filter, or ${limit.kind === "request" ? "move the work into a function or job with longQueries: true" : "give it longQueries: true"}, whose queries may run up to ${seconds(longQueryTimeoutMs)}.`;
+};
+/** The 504 of a query Postgres stopped, whose detail already names what ran too long. */
+var StatementTimeout = class extends HttpProblem {
+	constructor(subject, limit, extras = {}) {
+		super(504, "statement-timeout", "Gateway Timeout", statementTimeoutDetail(subject, limit), extras);
+	}
+};
+/** Runs `work`; a query of it the database stopped becomes the 504 that names `subject` and the limit it ran into. */
+const namingTimeouts = async (subject, limit, work) => {
+	try {
+		return await work();
+	} catch (error) {
+		if (isStatementTimeout(error)) throw new StatementTimeout(subject, limit);
+		throw error;
+	}
+};
+//#endregion
+export { StatementTimeout, defaultStatementTimeoutMs, isStatementTimeout, longQueryTimeoutMs, namingTimeouts, statementTimeoutDetail };

package/dist/types.d.ts

@@ -53,6 +53,15 @@ export type WriteEvent = {
 };
 /** Extension point of the write pipeline: a hook that throws rolls the write back. */
 export type PipelineHook = (event: WriteEvent, trx: Db) => Promise<void>;
+/**
+ * A check of a create or update before its transaction opens, with the body as the caller sent it, for what needs the
+ * network, such as resolving a host: it throws to refuse the write.
+ */
+export type WriteCheck = (write: {
+  resource: string;
+  operation: 'create' | 'update';
+  body: unknown;
+}) => Promise<void>;
 /** Where a request came from, as its headers say; proxies set `forwardedFor`, so it is only as trustworthy as they are. */
 export type AuditOrigin = {
   userAgent?: string;

package/dist/webhooks/table/validate-hook.js

@@ -5,9 +5,9 @@ import { parseEvents } from "./options.js";
 const isHeaders = (value) => value === null || value === void 0 || typeof value === "object" && !Array.isArray(value) && Object.values(value).every((item) => typeof item === "string");
 /**
 * Checks a webhook subscription as it is written: events that are declared, a filter that checks against every resource
-* it covers, headers of text, and a URL at a public address. A refusal is a 400 problem, and the write rolls back.
+* it covers, and headers of text. A refusal is a 400 problem, and the write rolls back.
 */
-const subscriptionWriteCheck = (models, checkUrl) => async (event) => {
+const subscriptionWriteCheck = (models) => async (event) => {
 	if (event.resource.name !== "webhook_subscriptions" || !event.after) return;
 	const { events, url, filter, headers } = event.after;
 	const candidate = {
@@ -24,9 +24,18 @@ const subscriptionWriteCheck = (models, checkUrl) => async (event) => {
 		...subscriptionProblems([candidate], models, []).map((problem) => problem.replace("Subscription \"it\" ", "")),
 		...isHeaders(headers) ? [] : ["headers must be an object of text values"]
 	];
-	const blocked = problems.length === 0 && checkUrl ? await checkUrl(url) : void 0;
-	const all = [...problems, ...blocked ? [blocked] : []];
-	if (all.length > 0) throw badRequest("invalid-webhook-subscription", `The webhook subscription cannot be saved: ${all.join("; ")}`);
+	if (problems.length > 0) throw badRequest("invalid-webhook-subscription", `The webhook subscription cannot be saved: ${problems.join("; ")}`);
+};
+/**
+* Checks the URL a webhook subscription is given before its write's transaction opens, since that resolves its host:
+* it must be at a public address. A URL that does not parse is left to `subscriptionWriteCheck`.
+*/
+const subscriptionUrlCheck = (checkUrl) => async ({ resource, body }) => {
+	if (resource !== "webhook_subscriptions" || typeof body !== "object" || body === null) return;
+	const { url } = body;
+	if (typeof url !== "string" || !URL.canParse(url)) return;
+	const blocked = await checkUrl(url);
+	if (blocked) throw badRequest("invalid-webhook-subscription", `The webhook subscription cannot be saved: ${blocked}`);
 };
 //#endregion
-export { subscriptionWriteCheck };
+export { subscriptionUrlCheck, subscriptionWriteCheck };

package/dist/write-pipeline.js

@@ -3,10 +3,10 @@ import { tenantScope } from "./tenant.js";
 import { requestAccess, requireOperation, targetFilter, writableFields } from "./request-access.js";
 import { actorSettings, wakeDispatch } from "./changes/actor.js";
 import { isDatabaseError } from "./error-handler.js";
+import { attachFiles, scheduleRemovedFiles } from "./files/attach.js";
 import { writeTransaction } from "./transactions.js";
 import { bindingOf, pendingBinding } from "./encryption/binding.js";
 import { deleteRecord, fetchRecord, insertRecord, restoreRecord, updateRecord } from "./records.js";
-import { attachFiles } from "./files/attach.js";
 import { assertWritten, checkParents, checkPrecondition, decide, denied, firstKeyField, keyOf, missing, notifier, shown } from "./write-shared.js";
 import { blockedDelete } from "./blocked-delete.js";
 import { encryptedValuesOf, hasEncryptedValues, sealValues } from "./encryption/seal-values.js";
@@ -31,7 +31,7 @@ const bindEncrypted = async (trx, deps, access, row, inserted, shape) => {
 	if (!bound) throw new Error(`A ${entry.name} record was created whose key the API cannot address, so its encrypted fields cannot be bound to it`);
 	return bound;
 };
-const create = async (trx, deps, access, body) => {
+const create = async (trx, deps, access, body, removed) => {
 	const { entry, full } = access;
 	const scope = tenantScope(entry, access.session);
 	const tenantValues = full.tenant && scope ? { [full.tenant]: scope.tenantValue } : {};
@@ -52,13 +52,13 @@ const create = async (trx, deps, access, body) => {
 		key: keyOf(access, created.record),
 		before: null
 	}]);
-	await notifier(deps, access)(trx, "create", void 0, created.record);
+	await notifier(deps, access, removed)(trx, "create", void 0, created.record);
 	return shown(access, created);
 };
-const update = async (trx, deps, access, request) => {
+const update = async (trx, deps, access, request, removed) => {
 	const plan = await planUpdate(trx, access, request.key, request.body, request.ifMatch);
 	if (Object.keys(plan.values).length === 0) return shown(access, plan.current);
-	const updated = await applyUpdate(trx, deps, access, request.key, plan);
+	const updated = await applyUpdate(trx, deps, access, request.key, plan, removed);
 	const rank = access.full.position?.field;
 	if (rank && rank in plan.values) await checkRankAfter(trx, deps, access, rank, [{
 		key: keyOf(access, updated.record),
@@ -66,7 +66,7 @@ const update = async (trx, deps, access, request) => {
 	}]);
 	return shown(access, updated);
 };
-const removeOrRestore = async (trx, deps, access, request) => {
+const removeOrRestore = async (trx, deps, access, request, removed) => {
 	const { entry, full } = access;
 	const undelete = request.operation === "undelete";
 	if (undelete && !full.softDelete) throw badRequest("undelete-unsupported", `Resource "${entry.name}" does not soft delete, so there is nothing to undelete`);
@@ -93,42 +93,56 @@ const removeOrRestore = async (trx, deps, access, request) => {
 		fields: [firstKeyField(access)]
 	})) throw denied(entry, operation);
 	await checkParents(trx, access, operation)(current.record);
-	const notify = notifier(deps, access);
+	const notify = notifier(deps, access, removed);
 	if (undelete) {
 		const restored = await restoreRecord(trx, entry, request.key, scope?.tenantValue, shape);
 		await assertWritten(trx, access, restored, "undelete", access.resolved.rowFilter.update, filter);
 		await notify(trx, "undelete", current.record, restored.record);
 		return shown(access, restored);
 	}
-	const removed = await deleteRecord(trx, entry, request.key, scope?.tenantValue, shape).catch(async (error) => {
+	const gone = await deleteRecord(trx, entry, request.key, scope?.tenantValue, shape).catch(async (error) => {
 		if (isDatabaseError(error) && error.code === "23503") throw await blockedDelete(deps, access, error);
 		throw error;
 	});
 	await notify(trx, "delete", current.record, void 0);
-	return shown(access, removed);
+	return shown(access, gone);
 };
 /**
 * One write inside an open transaction, for a caller whose access is already resolved: operations and field access,
 * tenant scope, validation against the fields they may write, optimistic concurrency, row filters and record-level
 * rules checked in the database, then the hooks; a rank written by the resource's position with `after` must keep the
-* record below what it depends on (see `checkRankAfter`). Batches run many of these in one transaction.
+* record below what it depends on (see `checkRankAfter`). The files it takes out of the row go to `removed`, which the
+* caller schedules for deletion once the transaction commits (`scheduleRemovedFiles`). Batches run many of these in one
+* transaction.
 */
-const writeIn = async (trx, deps, access, request) => {
+const writeIn = async (trx, deps, access, request, removed) => {
 	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
-	if (request.operation === "create") return create(trx, deps, access, request.body);
-	if (request.operation === "update") return update(trx, deps, access, request);
-	return removeOrRestore(trx, deps, access, request);
+	if (request.operation === "create") return create(trx, deps, access, request.body, removed);
+	if (request.operation === "update") return update(trx, deps, access, request, removed);
+	return removeOrRestore(trx, deps, access, request, removed);
+};
+/** Runs the checks that come before a create's or update's transaction opens (`WriteCheck`) on the body as sent. */
+const checkBeforeWrite = async (deps, write) => {
+	for (const check of deps.writeChecks) await check(write);
 };
 /**
-* The path every single write takes: resolve access once, then `writeIn` in its own transaction with a statement timeout.
-* The caller has already authenticated `session`; `form` is the public form a visitor creates through.
+* The path every single write takes: resolve access once, the checks that come before the transaction, then `writeIn`
+* in its own transaction with a statement timeout. The caller has already authenticated `session`; `form` is the
+* public form a visitor creates through.
 */
 const runWrite = async (deps, entry, session, request, form) => {
 	const access = await requestAccess(deps, entry, session, form);
 	requireOperation(access, request.operation === "undelete" ? "update" : request.operation);
-	const result = await writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request), actorSettings(deps, session));
+	if (request.operation === "create" || request.operation === "update") await checkBeforeWrite(deps, {
+		resource: entry.name,
+		operation: request.operation,
+		body: request.body
+	});
+	const removed = [];
+	const result = await writeTransaction(deps.db, deps.statementTimeoutMs, (trx) => writeIn(trx, deps, access, request, removed), actorSettings(deps, session));
+	await scheduleRemovedFiles(deps, removed);
 	wakeDispatch(deps);
 	return result;
 };
 //#endregion
-export { runWrite, writeIn };
+export { checkBeforeWrite, runWrite, writeIn };

package/dist/write-shared.js

@@ -2,10 +2,10 @@ import { maskEncrypted } from "./encryption/mask-stored.js";
 import { forbidden, notFound, preconditionFailed, preconditionRequired } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { andFilters, recordDecision } from "./request-access.js";
+import { removedFiles } from "./files/attach.js";
 import { ifMatchSatisfied } from "./etag.js";
 import { pickFields } from "./rows.js";
 import { fetchRecord } from "./records.js";
-import { scheduleRemovedFiles } from "./files/attach.js";
 import { parentGuard } from "./parent-access.js";
 import { presentFiles } from "./files/present.js";
 //#region src/write-shared.ts
@@ -53,8 +53,11 @@ const shown = async (access, written) => ({
 	record: (await presentFiles(access, [pickFields(written.record, Object.keys(access.model.fields))]))[0],
 	etag: written.etag
 });
-/** Runs the pipeline hooks for one write, inside the transaction. */
-const notifier = (deps, access) => async (trx, kind, before, after) => {
+/**
+* Runs the pipeline hooks for one write, inside the transaction, and adds the files it took out of its row to `removed`,
+* which the write schedules for deletion once it commits.
+*/
+const notifier = (deps, access, removed) => async (trx, kind, before, after) => {
 	const { session } = access;
 	const event = {
 		operation: kind,
@@ -66,7 +69,7 @@ const notifier = (deps, access) => async (trx, kind, before, after) => {
 		...after && { after: maskEncrypted(access.full, after) }
 	};
 	for (const hook of deps.hooks) await hook(event, trx);
-	await scheduleRemovedFiles(access, kind, before, after);
+	removed.push(...removedFiles(access, kind, before, after));
 };
 //#endregion
 export { assertWritten, checkParents, checkPrecondition, decide, denied, firstKeyField, keyOf, missing, notifier, shown };

package/dist/write-update.js

@@ -1,9 +1,9 @@
 import { badRequest } from "./problem.js";
 import { tenantScope } from "./tenant.js";
 import { targetFilter } from "./request-access.js";
+import { attachFiles } from "./files/attach.js";
 import { bindingOf } from "./encryption/binding.js";
 import { fetchRecord, updateRecord } from "./records.js";
-import { attachFiles } from "./files/attach.js";
 import { assertWritten, checkParents, checkPrecondition, decide, denied, firstKeyField, missing, notifier } from "./write-shared.js";
 import { sealValues } from "./encryption/seal-values.js";
 import { validateBody } from "./validate-body.js";
@@ -48,8 +48,8 @@ const refuseKeyChange = (access, plan) => {
 	if (!Object.values(full.fields).some((field) => field.encrypted)) return;
 	if (full.primaryKey.some((name) => Object.hasOwn(plan.values, name) && String(plan.values[name]) !== String(plan.current.record[name]))) throw badRequest("key-change-unsupported", `The key of a ${entry.name} record cannot change: its encrypted fields are bound to it`);
 };
-/** Writes a planned update, checks the row as written against the filters, and runs the hooks. */
-const applyUpdate = async (trx, deps, access, key, plan) => {
+/** Writes a planned update, checks the row as written against the filters, and runs the hooks (see `notifier`). */
+const applyUpdate = async (trx, deps, access, key, plan, removed) => {
 	const { entry, full } = access;
 	refuseKeyChange(access, plan);
 	const tenant = tenantScope(entry, access.session)?.tenantValue;
@@ -57,7 +57,7 @@ const applyUpdate = async (trx, deps, access, key, plan) => {
 	const updated = await updateRecord(trx, entry, key, tenant, values, { etagFields: Object.keys(access.model.fields) });
 	await assertWritten(trx, access, updated, "update", access.resolved.rowFilter.update, plan.filter);
 	await plan.parents(updated.record);
-	await notifier(deps, access)(trx, "update", plan.current.record, updated.record);
+	await notifier(deps, access, removed)(trx, "update", plan.current.record, updated.record);
 	return updated;
 };
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/server",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "description": "The Protobase REST API as a Hono app, with Better Auth sign-in.",
   "license": "Apache-2.0",
   "repository": {
@@ -36,9 +36,9 @@
     "@better-auth/passkey": "^1.7.12",
     "@better-auth/sso": "^1.7.12",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@protobase/layout": "0.43.1",
-    "@protobase/query": "0.43.1",
-    "@protobase/schema": "0.43.1",
+    "@protobase/layout": "0.44.0",
+    "@protobase/query": "0.44.0",
+    "@protobase/schema": "0.44.0",
     "@react-email/render": "^2.1.0",
     "@scalar/hono-api-reference": "^0.12.10",
     "@sentry/core": "^11.7.0",