@fabrika/db 0.8.2 → 0.9.0-cloudflare.2

package/src/database.ts

@@ -1,12 +1,41 @@
-import { SQL } from 'bun'
-import { CompiledQuery, createQueryId, type Dialect, Kysely, PostgresQueryCompiler, type RootOperationNode, type TransactionBuilder } from 'kysely'
-import { PostgresJSDialect } from 'kysely-postgres-js'
+import { CompiledQuery, createQueryId, type Dialect, Kysely, PostgresQueryCompiler, type QueryCompiler, type RootOperationNode } from 'kysely'
 import { databaseError, QueryRefusedError } from './errors'
 import { assertAllowedTree, type GuardContext } from './guard'
 import { isPlainIdentifier } from './identifier'
 
-type LooseDB = Record<string, Record<string, unknown>>
-type Executor = Pick<Kysely<LooseDB>, 'executeQuery'>
+export type LooseDB = Record<string, Record<string, unknown>>
+/** What a statement runs on: the database's own executor, or the one of the transaction it runs in. */
+export type Executor = Pick<Kysely<LooseDB>, 'executeQuery'>
+
+/** The SQL a database speaks: Postgres on Bun, SQLite in a Cloudflare Durable Object (ADR-0065). */
+export type SqlDialect = 'postgres' | 'sqlite'
+
+export interface TransactionOptions {
+	/**
+	 * A `READ ONLY` transaction on Postgres. SQLite opens none: each statement runs in a transaction of its own, which
+	 * rolls back a statement that wrote. A read-only session refuses writes either way.
+	 */
+	readonly readOnly: boolean
+	/** How long the transaction may sit idle before the database ends it; a database without the setting ignores it. */
+	readonly idleTimeoutMs?: number
+}
+
+/**
+ * Runs `body` in one transaction, on the executor it hands it: commits when `body` resolves, rolls back when it
+ * rejects, and rejects with `body`'s error. Its BEGIN, COMMIT and ROLLBACK failures reject with the driver's error.
+ */
+export type TransactionRunner = <T>(options: TransactionOptions, body: (executor: Executor) => Promise<T>) => Promise<T>
+
+/** What a `Database` runs on: the driver, the compiler of its dialect, and how it opens a transaction. */
+export interface DatabaseEngine {
+	readonly dialect: SqlDialect
+	readonly kysely: Kysely<LooseDB>
+	/** Compiles every guarded tree; frozen, since a patch to it after the guard ran would bypass the guard. */
+	readonly compiler: QueryCompiler
+	readonly transaction: TransactionRunner
+	/** The application's schema, the connection's `search_path`; `undefined` where the database has none. */
+	readonly schema?: string
+}
 
 /**
  * With `prepare: false`, Bun.SQL sends every parameter as text and a Date as `Date#toString()`, which Postgres
@@ -25,14 +54,14 @@ function timestampText(date: Date): string {
 	return date.toISOString()
 }
 
-const compiler = new ParameterCompiler()
-freezePrototypeChain(compiler)
+const postgresCompiler = new ParameterCompiler()
+freezePrototypeChain(postgresCompiler)
 
 /**
  * The compiler turns the guarded tree into SQL, so a patch to it after the guard ran would bypass the guard.
  * Freezing it when this module loads, before application modules, makes such a patch throw instead.
  */
-function freezePrototypeChain(object: object): void {
+export function freezePrototypeChain(object: object): void {
 	let current: object | null = object
 	while (current !== null && current !== Object.prototype) {
 		Object.freeze(current)
@@ -56,63 +85,73 @@ export function applicationSchema(appId: string): string {
 	return `app_${appId.replaceAll('-', '_')}`
 }
 
-export interface PostgresOptions {
-	readonly url: string
-	/** The application's schema (`app_<id>`), set as the connection's `search_path`. */
-	readonly schema: string
-	readonly max?: number
+const SQL_IDLE_TIMEOUT = "select set_config('idle_in_transaction_session_timeout', $1, true)"
+
+/** Postgres over Kysely's own transaction builder. */
+function postgresTransaction(kysely: Kysely<LooseDB>): TransactionRunner {
+	return (options, body) => {
+		const builder = kysely.transaction()
+		return (options.readOnly ? builder.setAccessMode('read only') : builder).execute(async (transaction) => {
+			if (options.idleTimeoutMs !== undefined) {
+				await transaction.executeQuery(CompiledQuery.raw(SQL_IDLE_TIMEOUT, [String(options.idleTimeoutMs)]))
+			}
+			return body(transaction)
+		})
+	}
 }
 
 let openSession: (database: Database, readOnly: boolean) => Session
-let transactionBuilder: (database: Database) => TransactionBuilder<LooseDB>
+let engineOf: (database: Database) => DatabaseEngine
 let firstConnection: (database: Database) => Promise<void>
 
 /** The connection the data layer runs on. It has no public query method: everything goes through a store. */
 export class Database {
-	readonly #kysely: Kysely<LooseDB>
-	readonly #schema: string | undefined
+	readonly #engine: DatabaseEngine
 
-	private constructor(kysely: Kysely<LooseDB>, schema: string | undefined) {
-		this.#kysely = kysely
-		this.#schema = schema
+	private constructor(engine: DatabaseEngine) {
+		if (engine.schema !== undefined && !isPlainIdentifier(engine.schema)) {
+			throw new QueryRefusedError('invalid_name', 'the schema must match ^[a-z_][a-z0-9_]*$')
+		}
+		this.#engine = Object.freeze({ ...engine })
 		Object.freeze(this)
 	}
 
 	static {
-		openSession = (database, readOnly) => new Session(database.#kysely, database.#kysely, readOnly)
-		transactionBuilder = (database) => database.#kysely.transaction()
+		openSession = (database, readOnly) => new Session(database.#engine.kysely, database.#engine, false, readOnly)
+		engineOf = (database) => database.#engine
 		firstConnection = async (database) => {
-			await database.#kysely.executeQuery(CompiledQuery.raw('SELECT 1'))
+			await database.#engine.kysely.executeQuery(CompiledQuery.raw('SELECT 1'))
 		}
 	}
 
 	/**
-	 * Over `Bun.SQL` with `prepare: false`: Bun otherwise keeps one prepared statement per distinct SQL text per
-	 * connection, and `in` lists of different lengths make that grow without bound.
+	 * Any Kysely Postgres dialect: `@fabrika/db/postgres` opens Bun.SQL through it, tests use one that records statements
+	 * instead of sending them.
 	 */
-	static postgres(options: PostgresOptions): Database {
-		if (!isPlainIdentifier(options.schema)) {
-			throw new QueryRefusedError('invalid_name', 'the schema must match ^[a-z_][a-z0-9_]*$')
-		}
-		const pool = new SQL({ url: options.url, adapter: 'postgres', prepare: false, max: options.max ?? 10, connection: { search_path: options.schema } })
-		return new Database(new Kysely<LooseDB>({ dialect: new PostgresJSDialect({ postgres: pool }) }), options.schema)
+	static fromDialect(dialect: Dialect, options: { readonly schema?: string } = {}): Database {
+		const kysely = new Kysely<LooseDB>({ dialect })
+		return new Database({ dialect: 'postgres', kysely, compiler: postgresCompiler, transaction: postgresTransaction(kysely), schema: options.schema })
 	}
 
-	/** Any Kysely Postgres dialect; tests use one that records statements instead of sending them. */
-	static fromDialect(dialect: Dialect): Database {
-		return new Database(new Kysely<LooseDB>({ dialect }), undefined)
+	/** A database of another dialect (`@fabrika/db/sqlite`), with its own frozen compiler and transaction runner. */
+	static fromEngine(engine: DatabaseEngine): Database {
+		return new Database(engine)
 	}
 
-	/** The application's schema, the connection's `search_path`; `undefined` over a bare dialect. */
+	get dialect(): SqlDialect {
+		return this.#engine.dialect
+	}
+
+	/** The application's schema, the connection's `search_path`; `undefined` over a bare dialect and on SQLite. */
 	get schema(): string | undefined {
-		return this.#schema
+		return this.#engine.schema
 	}
 
 	async close(): Promise<void> {
-		await this.#kysely.destroy()
+		await this.#engine.kysely.destroy()
 	}
 }
-// Application modules load after this one: a replaced `postgres` would receive the database URL.
+// Application modules load after this one: a replaced opener would receive the database's connection.
 Object.freeze(Database)
 Object.freeze(Database.prototype)
 
@@ -171,13 +210,15 @@ function untilAborted<T>(work: Promise<T>, signal: AbortSignal | undefined): Pro
  */
 export class Session {
 	readonly #executor: Executor
-	readonly #kysely: Kysely<LooseDB> | undefined
+	readonly #engine: DatabaseEngine
+	readonly #inTransaction: boolean
 	readonly #readOnly: boolean
 	readonly #hooks: SessionHooks
 
-	constructor(executor: Executor, kysely: Kysely<LooseDB> | undefined, readOnly: boolean, hooks: SessionHooks = {}) {
+	constructor(executor: Executor, engine: DatabaseEngine, inTransaction: boolean, readOnly: boolean, hooks: SessionHooks = {}) {
 		this.#executor = executor
-		this.#kysely = kysely
+		this.#engine = engine
+		this.#inTransaction = inTransaction
 		this.#readOnly = readOnly
 		this.#hooks = hooks
 		Object.freeze(this)
@@ -191,6 +232,11 @@ export class Session {
 		return this.#readOnly
 	}
 
+	/** The dialect of the database this session runs on: a framework statement picks its text by it. */
+	get dialect(): SqlDialect {
+		return this.#engine.dialect
+	}
+
 	/** Fails the transaction this session runs in, so it commits nothing: a statement refused before it was sent. */
 	fail(): void {
 		this.#hooks.failed?.()
@@ -214,11 +260,10 @@ export class Session {
 			throw new QueryRefusedError('read_only', 'this request is read-only: it reads, and no operation may write or lock a row')
 		}
 		// CompiledQuery's row type is a phantom: this is the one place where generated row types meet the wire.
-		const compiled: CompiledQuery<O> = compiler.compileQuery(node, createQueryId())
-		const kysely = this.#kysely
-		if (this.#readOnly && kysely !== undefined) {
+		const compiled: CompiledQuery<O> = this.#engine.compiler.compileQuery(node, createQueryId())
+		if (this.#readOnly && !this.#inTransaction) {
 			try {
-				const result = await kysely.transaction().setAccessMode('read only').execute((transaction) => transaction.executeQuery(compiled))
+				const result = await this.#engine.transaction({ readOnly: true }, (executor) => executor.executeQuery(compiled))
 				return result.rows
 			} catch (error) {
 				throw databaseError(error)
@@ -234,15 +279,14 @@ export class Session {
 	 * `work` returned or not; its session then runs nothing more.
 	 */
 	async transaction<T>(work: (session: Session) => Promise<T>, signal?: AbortSignal): Promise<T> {
-		if (this.#kysely === undefined) {
+		if (this.#inTransaction) {
 			return work(this)
 		}
-		const builder = this.#kysely.transaction()
 		let open = true
 		let failed = false
 		let failure: { readonly error: unknown } | undefined
 		try {
-			return await (this.#readOnly ? builder.setAccessMode('read only') : builder).execute(async (transaction) => {
+			return await this.#engine.transaction({ readOnly: this.#readOnly }, async (executor) => {
 				try {
 					const hooks: SessionHooks = {
 						open: () => open,
@@ -250,7 +294,7 @@ export class Session {
 							failed = true
 						},
 					}
-					const result = await untilAborted(work(new Session(transaction, undefined, this.#readOnly, hooks)), signal)
+					const result = await untilAborted(work(new Session(executor, this.#engine, true, this.#readOnly, hooks)), signal)
 					// A failure the work caught: Postgres would answer the COMMIT of an aborted transaction with a silent ROLLBACK.
 					if (failed) {
 						throw new QueryRefusedError('statement_failed', 'a statement of this transaction failed, so nothing it wrote commits')
@@ -274,11 +318,43 @@ Object.freeze(Session.prototype)
 /** How long an invocation's transaction may sit idle before Postgres ends it, and its connection with it. */
 export const INVOCATION_IDLE_TIMEOUT_MS = 30_000
 
-const SQL_IDLE_TIMEOUT = "select set_config('idle_in_transaction_session_timeout', $1, true)"
-
 /** What the invocation's transaction body throws to roll back; never seen outside this module. */
 class RolledBack extends Error {}
 
+/** A writing invocation that holds its object's storage transaction longer than this logs one line. */
+export const TRANSACTION_HELD_LOG_MS = 1_000
+/** A writing invocation that holds its object's storage transaction longer than this is also reported. */
+export const TRANSACTION_HELD_REPORT_MS = 5_000
+
+/** Where an enclosure tells how long it held its object: every other event of the object waited that long. */
+export interface HoldWatch {
+	/** The site the invocation serves, which the log line names. */
+	readonly site: string
+	/** Hears a hold longer than `TRANSACTION_HELD_REPORT_MS`, in whole ms. */
+	readonly held: (heldMs: number) => void
+}
+
+/**
+ * Runs once the transaction settled, so it never throws: a failed log or report must not turn a committed invocation
+ * into a failed one. Each has its own guard; the line names the site and the ms only, never a value or a statement.
+ */
+function reportHold(watch: HoldWatch, heldMs: number): void {
+	try {
+		if (heldMs > TRANSACTION_HELD_LOG_MS) {
+			console.warn(`fabrika: ${watch.site}: held its object's transaction for ${heldMs} ms`)
+		}
+	} catch {
+		// The report below still goes out.
+	}
+	try {
+		if (heldMs > TRANSACTION_HELD_REPORT_MS) {
+			watch.held(heldMs)
+		}
+	} catch {
+		// The hold was logged; the invocation's own outcome stands.
+	}
+}
+
 /**
  * The one transaction of an invocation (a request, a webhook delivery): opened by its first statement, then ended
  * once by the framework — committed after the handler returned and its output passed validation, rolled back
@@ -289,6 +365,7 @@ class RolledBack extends Error {}
 export class InvocationTransaction {
 	readonly #database: Database
 	readonly #readOnly: boolean
+	readonly #now: () => number
 	readonly #decision = Promise.withResolvers<'commit' | 'rollback'>()
 	#opened: Promise<Session> | undefined
 	#run: Promise<void> | undefined
@@ -296,10 +373,15 @@ export class InvocationTransaction {
 	#isReleased = true
 	#ended = false
 	#failed = false
+	/** Inside `enclose` on SQLite: `commit()` and `rollback()` only decide, and the enclosure ends the transaction. */
+	#enclosed = false
+	#decided: 'commit' | 'rollback' | undefined
 
-	constructor(database: Database, readOnly: boolean) {
+	/** `now` is the clock an enclosure's hold is measured by. */
+	constructor(database: Database, readOnly: boolean, now: () => number = Date.now) {
 		this.#database = database
 		this.#readOnly = readOnly
+		this.#now = now
 	}
 
 	/** A `READ ONLY` transaction: a query's or an export's. */
@@ -327,6 +409,65 @@ export class InvocationTransaction {
 		return this.#isReleased
 	}
 
+	/**
+	 * Runs `work`: the invocation from its handler to its `commit()`. On SQLite a writing invocation's transaction
+	 * encloses `work`, opened before it: a Durable Object's transaction holds back every other event, the answers to the
+	 * object's own I/O included, until its callback ends, so the handler runs inside it. There `commit()` and `rollback()`
+	 * decide, the COMMIT runs once `work` returned, and a failed COMMIT rejects with a `DatabaseError`. A read-only
+	 * invocation, and every invocation elsewhere, runs `work` as is: a read-only one on SQLite holds no storage
+	 * transaction, so the object serves other events while it awaits.
+	 *
+	 * Only the SQLite enclosure is measured for `watch`, from entering the transaction until it settled: it holds the
+	 * whole object, where a Postgres transaction holds one pooled connection and other requests go on.
+	 */
+	async enclose<T>(work: () => Promise<T>, watch: HoldWatch): Promise<T> {
+		const engine = engineOf(this.#database)
+		if (engine.dialect !== 'sqlite' || this.#readOnly) {
+			return work()
+		}
+		if (this.#opened !== undefined || this.#ended) {
+			throw new QueryRefusedError('ended', 'an invocation encloses its work before its first statement')
+		}
+		this.#enclosed = true
+		this.#isReleased = false
+		let result: { readonly value: T } | undefined
+		let entered: number | undefined
+		try {
+			await engine.transaction({ readOnly: this.#readOnly }, async (executor) => {
+				entered = this.#now()
+				const session = new Session(executor, engine, true, this.#readOnly, {
+					failed: () => {
+						this.#failed = true
+					},
+					open: () => !this.#ended,
+				})
+				this.#opened = Promise.resolve(session)
+				result = { value: await work() }
+				this.#ended = true
+				if (this.#decided !== 'commit') {
+					throw new RolledBack()
+				}
+			})
+		} catch (error) {
+			if (result === undefined) {
+				throw error
+			}
+			if (!(error instanceof RolledBack)) {
+				throw databaseError(error)
+			}
+		} finally {
+			this.#ended = true
+			this.#isReleased = true
+			if (entered !== undefined) {
+				reportHold(watch, Math.round(this.#now() - entered))
+			}
+		}
+		if (result === undefined) {
+			throw new QueryRefusedError('ended', 'the transaction ended before the invocation answered')
+		}
+		return result.value
+	}
+
 	/** The session the invocation's statements run in; the first call opens the transaction. */
 	session(): Promise<Session> {
 		if (this.#ended) {
@@ -339,15 +480,15 @@ export class InvocationTransaction {
 	#open(): Promise<Session> {
 		const ready = Promise.withResolvers<Session>()
 		this.#isReleased = false
-		const builder = transactionBuilder(this.#database)
-		const run = (this.#readOnly ? builder.setAccessMode('read only') : builder).execute(async (transaction) => {
-			const session = new Session(transaction, undefined, this.#readOnly, {
+		const engine = engineOf(this.#database)
+		const options: TransactionOptions = { readOnly: this.#readOnly, idleTimeoutMs: INVOCATION_IDLE_TIMEOUT_MS }
+		const run = engine.transaction(options, async (executor) => {
+			const session = new Session(executor, engine, true, this.#readOnly, {
 				failed: () => {
 					this.#failed = true
 				},
 				open: () => !this.#ended,
 			})
-			await executeFixed(session, CompiledQuery.raw(SQL_IDLE_TIMEOUT, [String(INVOCATION_IDLE_TIMEOUT_MS)]))
 			ready.resolve(session)
 			if ((await this.#decision.promise) === 'rollback') {
 				throw new RolledBack()
@@ -371,6 +512,13 @@ export class InvocationTransaction {
 			throw new QueryRefusedError('ended', 'this invocation has already ended')
 		}
 		this.#ended = true
+		if (this.#enclosed) {
+			this.#decided = this.#failed ? 'rollback' : 'commit'
+			if (this.#failed) {
+				throw new QueryRefusedError('statement_failed', 'a statement of this invocation failed, so nothing it wrote commits')
+			}
+			return
+		}
 		const run = this.#run
 		if (this.#failed) {
 			this.#decision.resolve('rollback')
@@ -390,9 +538,13 @@ export class InvocationTransaction {
 		}
 	}
 
-	/** Discards what the invocation wrote; idempotent, never throws, and returns once the connection is back. */
+	/** Discards what the invocation wrote; idempotent, never throws, and returns once the connection is back (inside `enclose`, it only decides). */
 	async rollback(): Promise<void> {
 		this.#ended = true
+		if (this.#enclosed) {
+			this.#decided ??= 'rollback'
+			return
+		}
 		this.#decision.resolve('rollback')
 		await this.#released
 	}

package/src/errors.ts

@@ -55,6 +55,7 @@ export const QUERY_REFUSALS = {
 	sql_function: 'ctx.sql calls a function that is not a reviewed built-in',
 	sql_outside_transaction: 'a job runs ctx.sql only inside ctx.transaction((tx) => …), as tx.sql',
 	sql_scope: 'ctx.sql.scope(…) stands alone, joined by AND, in a WHERE or JOIN … ON clause of its own invocation',
+	sql_dialect: 'ctx.sql runs only on Postgres; an application on SQLite (Cloudflare) reads and writes through ctx.db',
 	file_scan: "a scan verdict outside the scan job's lease",
 	claim_site: 'claim leases rows in a transaction of its own: a job calls it on ctx.db, never inside ctx.transaction or a request',
 	on_conflict: "an insert's onConflict names no column of the table, a column the insert leaves empty, or another action",

package/src/file-columns.ts

@@ -125,7 +125,10 @@ export async function storedRowScope(model: TableModel, session: Session, key: s
 	if (!isPlainIdentifier(model.name) || !isPlainIdentifier(column) || !isPlainIdentifier(key)) {
 		throw new QueryRefusedError('invalid_name', "a file column's table is named by plain identifiers")
 	}
-	const [found] = await runFixedStatement(session, `select ${column}::text as scope from ${model.name} where ${key}::text = $1`, [keyValue])
+	const statement = session.dialect === 'sqlite'
+		? `select cast(${column} as text) as scope from ${model.name} where cast(${key} as text) = ?1`
+		: `select ${column}::text as scope from ${model.name} where ${key}::text = $1`
+	const [found] = await runFixedStatement(session, statement, [keyValue])
 	const value: unknown = typeof found === 'object' && found !== null ? ownDescriptor(found, 'scope')?.value : undefined
 	if (typeof value !== 'string') {
 		throw new NotFoundError(`${model.name} not found`)

package/src/framework-tables.ts

@@ -8,6 +8,7 @@ import { BinaryOperationNode, type OperationNode, OperatorNode, ValueNode } from
 import { runFixedStatement, type Session, sessionOf } from './database'
 import { QueryRefusedError } from './errors'
 import type { GuardContext } from './guard'
+import type { DialectTexts } from './job-leases'
 import { WEBHOOK_BINDINGS_TABLE, WEBHOOK_DELIVERIES_TABLE } from './migrations'
 import { acknowledgement, allOf, column, deleteNode, equals, insertNode, locateNode, scopedWhere, updateNode } from './nodes'
 import type { DataLayerRuntime } from './store'
@@ -72,16 +73,35 @@ export interface DeliveryClaim {
 const D = WEBHOOK_DELIVERIES_TABLE
 
 /** A new key, or one whose claim expired without completion; a completed one (no lease) is never taken. */
-const SQL_CLAIM = `insert into ${D} (binding_id, delivery_id, received_at, lease_until) values ($1, $2, $3::bigint, $4::bigint)
+const SQL_CLAIM: DialectTexts = {
+	postgres: `insert into ${D} (binding_id, delivery_id, received_at, lease_until) values ($1, $2, $3::bigint, $4::bigint)
 on conflict (binding_id, delivery_id) do update set received_at = excluded.received_at, lease_until = excluded.lease_until
 where ${D}.lease_until is not null and ${D}.lease_until < excluded.received_at
-returning delivery_id`
+returning delivery_id`,
+	sqlite: `insert into ${D} (binding_id, delivery_id, received_at, lease_until) values (?1, ?2, ?3, ?4)
+on conflict (binding_id, delivery_id) do update set received_at = excluded.received_at, lease_until = excluded.lease_until
+where ${D}.lease_until is not null and ${D}.lease_until < excluded.received_at
+returning delivery_id`,
+}
 
-const SQL_COMPLETE = `update ${D} set lease_until = null
+const SQL_COMPLETE: DialectTexts = {
+	postgres: `update ${D} set lease_until = null
 where binding_id = $1 and delivery_id = $2 and lease_until = $3::bigint
-returning delivery_id`
+returning delivery_id`,
+	sqlite: `update ${D} set lease_until = null
+where binding_id = ?1 and delivery_id = ?2 and lease_until = ?3
+returning delivery_id`,
+}
 
-const SQL_RELEASE = `delete from ${D} where binding_id = $1 and delivery_id = $2 and lease_until = $3::bigint returning delivery_id`
+const SQL_RELEASE: DialectTexts = {
+	postgres: `delete from ${D} where binding_id = $1 and delivery_id = $2 and lease_until = $3::bigint returning delivery_id`,
+	sqlite: `delete from ${D} where binding_id = ?1 and delivery_id = ?2 and lease_until = ?3 returning delivery_id`,
+}
+
+/** Runs the text of `session`'s dialect. */
+function run(session: Session, texts: DialectTexts, parameters: readonly (string | number)[]): Promise<readonly unknown[]> {
+	return runFixedStatement(session, texts[session.dialect], parameters)
+}
 
 const BINDING_COLUMNS = ['id', 'webhook', 'scope_type', 'scope_value', 'account', 'secret']
 
@@ -186,17 +206,17 @@ export function webhookTables(runtime: () => DataLayerRuntime): WebhookTables {
 			)
 			const leaseUntil = now + leaseMs
 			// The primary key decides between concurrent copies of one delivery: exactly one inserts or takes over.
-			const claimed = await runFixedStatement(session(), SQL_CLAIM, [bindingId, deliveryKey, now, leaseUntil])
+			const claimed = await run(session(), SQL_CLAIM, [bindingId, deliveryKey, now, leaseUntil])
 			return claimed.length === 0 ? null : Object.freeze({ bindingId, key: deliveryKey, leaseUntil })
 		},
 
 		async completeDelivery(claim: DeliveryClaim, using?: Session): Promise<boolean> {
-			const completed = await runFixedStatement(using ?? session(), SQL_COMPLETE, [claim.bindingId, claim.key, claim.leaseUntil])
+			const completed = await run(using ?? session(), SQL_COMPLETE, [claim.bindingId, claim.key, claim.leaseUntil])
 			return completed.length > 0
 		},
 
 		async releaseDelivery(claim: DeliveryClaim): Promise<void> {
-			await runFixedStatement(session(), SQL_RELEASE, [claim.bindingId, claim.key, claim.leaseUntil])
+			await run(session(), SQL_RELEASE, [claim.bindingId, claim.key, claim.leaseUntil])
 		},
 	})
 }

package/src/framework.ts

@@ -3,7 +3,7 @@
 // hands the framework the locator its access check uses. Browser- and Worker-safe: the Worker adapter imports `boot`.
 
 import type { DataAccess } from './orm'
-import { frameworkSideOf, type FrameworkTables, type Locator } from './registry'
+import { frameworkSideOf, type FrameworkTables, type Locator, type ProvisionalBinding } from './registry'
 import type { DataLayerRuntime } from './store'
 
 export type { Admissions } from './admissions'
@@ -23,7 +23,7 @@ export { type FileHolding, fileHoldingOf, type FileReference, fileReference, hol
 export type { DeliveryClaim, NewWebhookBinding, WebhookBinding, WebhookTables } from './framework-tables'
 export type { JobLeases, JobLeaseState, JobOutcome, OverdueClaim } from './job-leases'
 export type { DataAccess, DataHandles, DataSite } from './orm'
-export type { FrameworkTables, Locator } from './registry'
+export type { FrameworkTables, Locator, ProvisionalBinding } from './registry'
 export type { SqlMode, SqlSite, SqlTag, SqlValue } from './sql'
 export type { FileColumnRef, QuarantinedStoredFile, ServedFile, StagedFile, StoredFileMeta, StoredFiles, StoredFileStatus } from './stored-files'
 
@@ -37,6 +37,14 @@ export function isScopedDatabase(value: unknown): boolean {
  * reach. Throws for any other value and for a layer that is already connected.
  */
 export function bindScopedDatabase(value: unknown, runtime: DataLayerRuntime): Locator {
+	return bindScopedDatabaseProvisionally(value, runtime).locate
+}
+
+/**
+ * Connects the layer like `bindScopedDatabase`, and answers with its locator the `release` that disconnects it again:
+ * a boot that fails releases the layer, so a later boot of the same application binds it. Throws as that does.
+ */
+export function bindScopedDatabaseProvisionally(value: unknown, runtime: DataLayerRuntime): ProvisionalBinding {
 	const side = frameworkSideOf(value)
 	if (side === undefined) {
 		throw new TypeError('not a data layer scoped(tables) created')

package/src/guard.ts

@@ -262,6 +262,14 @@ function checkNode(node: OperationNode, parent: Visit | undefined, context: Guar
 			return
 		case 'TableNode':
 			return checkTable(node, parent, context)
+		case 'OrderByItemNode': {
+			// Kysely prints `nulls` as raw text; the layer only ever states the order Postgres has by default.
+			const nulls = read(node, 'nulls')
+			if (nulls !== undefined && nulls !== 'first' && nulls !== 'last') {
+				throw new QueryRefusedError('statement_shape', 'an order term states nulls first or nulls last, nothing else')
+			}
+			return
+		}
 		case 'JoinNode':
 			return checkJoin(node, context)
 		case 'ReferenceNode':

package/src/index.ts

@@ -13,7 +13,15 @@ export type {
 	WithinGrant,
 } from './capability'
 export { MAX_WITHIN_VALUES } from './capability'
-export { applicationSchema, Database, type PostgresOptions } from './database'
+export {
+	applicationSchema,
+	Database,
+	type DatabaseEngine,
+	type Executor,
+	type SqlDialect,
+	type TransactionOptions,
+	type TransactionRunner,
+} from './database'
 export type {
 	AllowedOperator,
 	ComparisonOperator,