kern-orm 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as falseNode, C as equalityOperators, D as createList, E as defineGenericOperator, M as oneNode, N as trueNode, O as createNode, S as Column, T as isEqualityCompatible, _ as toNode, a as stringifyJson, b as defineType, c as textOperators, d as compareNodes, f as createIsNullNode, g as toExpression, h as toBooleanExpression, j as noFilters, k as createSelectNode, l as orderingOperators, m as isExpression, n as text, p as getType, s as encodeBytea, u as compare, v as toValueNode, x as isType } from "./text-4Xs09pIf.mjs";
+import { A as createList, C as isType, D as isEqualityCompatible, F as oneNode, I as trueNode, M as createSelectNode, N as falseNode, O as valuesQueryNode, P as noFilters, S as defineType, T as equalityOperators, _ as toBooleanExpression, a as stringifyJson, b as toValueNode, c as textOperators, d as compareNodes, f as createIsNullNode, g as operandNode, h as isOperandSource, j as createNode, k as defineGenericOperator, l as orderingOperators, m as isExpression, n as text, p as getType, s as encodeBytea, u as compare, v as toExpression, w as Column, x as getBooleanType, y as toNode } from "./text-BUNl8wpl.mjs";
 import { AsyncLocalStorage } from "node:async_hooks";
 // src/ast/boolean.ts
 /** Combines predicate nodes with `AND` or `OR`, flattening nested groups of the same kind. */
@@ -33,9 +33,10 @@ function combineFilters(filters) {
 	return combineNodes("and", operands);
 }
 // src/expression/predicates.ts
-/** Converts a condition operand into a node; an object of column values stays unresolved until `where`. */
+/** Converts a condition operand into a node: a query nests in it, and an object of column values stays unresolved until `where`. */
 function toConditionNode(operand) {
-	return isExpression(operand) ? toNode(operand) : createNode({
+	if (isOperandSource(operand)) return operand[operandNode]();
+	return createNode({
 		kind: "values",
 		values: operand
 	});
@@ -471,9 +472,11 @@ function needsParentheses(kind, position) {
 		case "param":
 		case "boolean":
 		case "values":
+		case "nestedQuery":
 		case "tableName":
 		case "subquery":
 		case "exists":
+		case "textSubquery":
 		case "aggregate": return false;
 		case "cast": return position === "interpolation";
 		case "raw": return position !== "interpolation";
@@ -482,6 +485,7 @@ function needsParentheses(kind, position) {
 		case "not":
 		case "comparison":
 		case "in":
+		case "inQuery":
 		case "isNull": return position !== "condition";
 		default: return kind;
 	}
@@ -709,12 +713,18 @@ function compileExpression(context, scope, node) {
 		case "or": return node.operands.map((operand) => compileOperand(context, scope, operand, "condition")).join(node.kind === "and" ? " AND " : " OR ");
 		case "not": return `NOT ${compileOperand(context, scope, node.operand, "condition")}`;
 		case "values": throw new Error("An object condition can only be used in `where`");
+		case "nestedQuery": throw new Error("A query in an expression must be lowered before compilation");
 		case "comparison": return `${compileOperand(context, scope, node.left, "value")} ${node.operator} ${compileOperand(context, scope, node.right, "value")}`;
 		case "in": {
 			let text = `${compileOperand(context, scope, node.operand, "value")} IN (${compileOperand(context, scope, node.list[0], "value")}`;
 			for (let index = 1; index < node.list.length; index++) text += `, ${compileOperand(context, scope, node.list[index], "value")}`;
 			return `${text})`;
 		}
+		case "inQuery": {
+			const { query } = node;
+			if (query.kind === "nestedQuery") throw new Error("A query in an expression must be lowered before compilation");
+			return `${compileOperand(context, scope, node.operand, "value")} IN ${compileSubquery(context, scope, query, "A subquery of IN")}`;
+		}
 		case "isNull": return `${compileOperand(context, scope, node.operand, "value")} IS NULL`;
 		case "raw": {
 			let text = node.fragments[0];
@@ -722,12 +732,9 @@ function compileExpression(context, scope, node) {
 			return text;
 		}
 		case "tableName": return compileInterpolatedTable(context, node);
-		case "subquery": {
-			const { length } = node.query.projections;
-			if (length !== 1) throw new Error(`A scalar subquery must select one field, not ${length}`);
-			return `(${compileQuery(context, scope, node.query)})`;
-		}
+		case "subquery": return compileSubquery(context, scope, node.query, "A scalar subquery");
 		case "exists": return `EXISTS (${compileQuery(context, scope, node.query)})`;
+		case "textSubquery": return `(${compileQuery(context, scope, node.query)})`;
 		case "aggregate": {
 			let text = `${node.name}(${node.distinct ? "DISTINCT " : ""}`;
 			for (let index = 0; index < node.arguments.length; index++) text += `${index === 0 ? "" : ", "}${compileExpression(context, scope, node.arguments[index])}`;
@@ -737,6 +744,12 @@ function compileExpression(context, scope, node) {
 		default: return node;
 	}
 }
+/** Compiles `query` in parentheses as a subquery of one field, and rejects a query of another number of fields, naming the subquery as `subject`. */
+function compileSubquery(context, scope, query, subject) {
+	const { length } = query.projections;
+	if (length !== 1) throw new Error(`${subject} must select one field, not ${length}`);
+	return `(${compileQuery(context, scope, query)})`;
+}
 /** Encodes the value of a parameter node with its type, or by its JavaScript type without one. */
 function encodeParameter(node) {
 	if (node.value === void 0) throw new TypeError("Query parameter is undefined; use null for NULL");
@@ -787,7 +800,8 @@ function visitNodes(node, deep, visit) {
 		case "param":
 		case "boolean":
 		case "tableName":
-		case "values": return;
+		case "values":
+		case "nestedQuery": return;
 		case "cast":
 		case "not":
 		case "isNull":
@@ -805,11 +819,16 @@ function visitNodes(node, deep, visit) {
 			visitNodes(node.operand, deep, visit);
 			for (const item of node.list) visitNodes(item, deep, visit);
 			return;
+		case "inQuery":
+			visitNodes(node.operand, deep, visit);
+			if (deep && node.query.kind === "select") visitQuery(node.query, visit);
+			return;
 		case "raw":
 			for (const value of node.values) visitNodes(value, deep, visit);
 			return;
 		case "subquery":
 		case "exists":
+		case "textSubquery":
 			if (deep) visitQuery(node.query, visit);
 			return;
 		case "aggregate":
@@ -834,12 +853,31 @@ function visitQuery(query, visit) {
 	if (query.limit !== void 0) visitNodes(query.limit, true, visit);
 	if (query.offset !== void 0) visitNodes(query.offset, true, visit);
 }
+// src/query/exists.ts
+let existsProjection;
+/** Returns the projection of whether a query has a row, the only projection of a query made by `exists`. */
+function getExistsProjection() {
+	existsProjection ??= Object.freeze({
+		key: "exists",
+		expression: trueNode,
+		type: getBooleanType()
+	});
+	return existsProjection;
+}
+/** Tells whether `node` is a query of `exists`, whose value is whether the rows that its filters, limit, and offset choose exist. */
+function isExistsQuery(node) {
+	return node.value && isExistsProjection(node.projections[0]);
+}
+/** Tells whether a selected field is the projection of `exists`, which only `exists` selects. */
+function isExistsProjection(field) {
+	return field === existsProjection;
+}
 // src/query/aggregate.ts
 /** Type of a count: a `bigint` of PostgreSQL decoded as a number, rejecting a count that a number cannot hold exactly. */
 const countType = /* @__PURE__ */ defineType({ sqlType: "bigint" }).transform({
 	decode: (text) => decodeSafeInteger(text, "Count"),
 	encode: (value) => String(value)
-});
+}).withOperators(orderingOperators);
 /** Types of the sums of the values of `smallint` and `integer` types, by the type of the values, created once for each. */
 const sumTypes = /* @__PURE__ */ new WeakMap();
 const noFallbacks = /* @__PURE__ */ Object.freeze([]);
@@ -961,6 +999,10 @@ function addFallback(field, fallback) {
 function isAggregateQuery(node) {
 	return node.value && isAggregateProjection(node.projections[0]);
 }
+/** Tells whether `node`, a nested query, is selected as its value rather than as packed rows: an aggregate query as a scalar subquery of its statement, and a query of `exists` as `EXISTS` of its rows. */
+function isSelectedAsValue(node) {
+	return isAggregateQuery(node) || isExistsQuery(node);
+}
 /** Tells whether a selected field is the projection of an aggregate, which only the aggregate methods select. */
 function isAggregateProjection(field) {
 	return "ordered" in field;
@@ -971,7 +1013,7 @@ function toCountType() {
 function toArgumentType(argument) {
 	return argument;
 }
-/** Returns the type of the sum of the values of type `argument`: for `smallint` and `integer` values, `argument` that rejects a sum that a number cannot hold exactly, and `argument` for others. */
+/** Returns the type of the sum of the values of type `argument`: for `smallint` and `integer` values, a `bigint` with the operators of `argument` that rejects a sum that a number cannot hold exactly, and `argument` for others. */
 function toSumType(argument) {
 	if (argument.castType !== "smallint" && argument.castType !== "integer") return argument;
 	let type = sumTypes.get(argument);
@@ -982,7 +1024,7 @@ function toSumType(argument) {
 				return argument.decode(text);
 			},
 			encode: (value) => argument.encode(value)
-		});
+		}).withOperators(argument.operators);
 		sumTypes.set(argument, type);
 	}
 	return type;
@@ -1370,66 +1412,112 @@ function createRef(source, key) {
 // src/lowering/lower.ts
 const noJoins = /* @__PURE__ */ Object.freeze([]);
 const noOrder = /* @__PURE__ */ Object.freeze([]);
+const noProjections = /* @__PURE__ */ Object.freeze([]);
 function lowerStatement(node, definitions, db) {
+	const context = {
+		definitions,
+		db
+	};
 	switch (node.kind) {
-		case "query": return lowerSelect(node, definitions, db, true);
-		case "record": return lowerRecord(node, definitions, db);
-		case "text": return node;
-		default: return lowerMutation(node, definitions, db);
+		case "query": return lowerSelect(node, context, true);
+		case "record": return lowerRecord(node, context);
+		case "text": return lowerText(node, context);
+		default: return lowerMutation(node, context);
 	}
 }
-/** Lowers a mutation to its statement, packing the rows of each nested query of `RETURNING` into the value of its field, or selecting the value of a nested aggregate query, as a select list does. */
-function lowerMutation(node, definitions, db) {
-	const { returning } = node;
-	const lowered = returning === void 0 ? void 0 : lowerProjections(returning, definitions, db);
-	if (lowered === returning) return node;
-	const { target, rows, value } = node;
+/** Lowers a statement of SQL text, replacing the queries in the expressions interpolated into it. */
+function lowerText(node, context) {
+	const sql = lowerExpression(node.sql, context);
+	if (sql === node.sql) return node;
+	return Object.freeze({
+		kind: "text",
+		sql,
+		fields: node.fields,
+		rows: node.rows,
+		value: node.value
+	});
+}
+/** Lowers a mutation to its statement, replacing the queries in its expressions, and packing the rows of each nested query of `RETURNING` into the value of its field, or selecting the value of a nested aggregate query, as a select list does. */
+function lowerMutation(node, context) {
+	const { target, returning, rows, value } = node;
+	const lowered = returning === void 0 ? void 0 : lowerProjections(returning, context);
 	switch (node.kind) {
-		case "insert": return Object.freeze({
-			kind: "insert",
-			target,
-			columns: node.columns,
-			values: node.values,
-			returning: lowered,
-			rows,
-			value
-		});
-		case "update": return Object.freeze({
-			kind: "update",
-			target,
-			set: node.set,
-			filters: node.filters,
-			returning: lowered,
-			rows,
-			value
-		});
-		case "delete": return Object.freeze({
-			kind: "delete",
-			target,
-			filters: node.filters,
-			returning: lowered,
-			rows,
-			value
-		});
+		case "insert": {
+			const values = lowerEach(node.values, context, lowerRow);
+			if (lowered === returning && values === node.values) return node;
+			return Object.freeze({
+				kind: "insert",
+				target,
+				columns: node.columns,
+				values,
+				returning: lowered,
+				rows,
+				value
+			});
+		}
+		case "update": {
+			const set = lowerEach(node.set, context, lowerAssignment);
+			const filters = lowerFilters(node.filters, context);
+			if (lowered === returning && set === node.set && filters === node.filters) return node;
+			return Object.freeze({
+				kind: "update",
+				target,
+				set,
+				filters,
+				returning: lowered,
+				rows,
+				value
+			});
+		}
+		case "delete": {
+			const filters = lowerFilters(node.filters, context);
+			if (lowered === returning && filters === node.filters) return node;
+			return Object.freeze({
+				kind: "delete",
+				target,
+				filters,
+				returning: lowered,
+				rows,
+				value
+			});
+		}
 		default: return node;
 	}
 }
+/** Lowers a row of `VALUES` of an insert, whose `undefined` stands for `DEFAULT`. */
+function lowerRow(row, context) {
+	return lowerEach(row, context, lowerValue);
+}
+function lowerValue(node, context) {
+	return node === void 0 ? void 0 : lowerExpression(node, context);
+}
+function lowerAssignment(assignment, context) {
+	const value = lowerExpression(assignment.value, context);
+	return value === assignment.value ? assignment : Object.freeze({
+		key: assignment.key,
+		value
+	});
+}
 /** Lowers a query as `lowerQuery` does, or as `lowerStatement` does when `positions` is set. */
-function lowerSelect(node, definitions, db, positions) {
+function lowerSelect(node, context, positions) {
+	if (isExistsQuery(node)) return selectExists(node, context);
+	checkRelation(node, context);
+	if (isAggregateQuery(node)) return lowerAggregate(node, context);
+	const selected = node.projections;
+	const projections = lowerProjections(selected, context);
+	const filters = lowerFilters(node.filters, context);
+	const orderBy = lowerOrder(node.orderBy, context, selected, projections);
 	const { relation } = node;
-	if (relation !== void 0 && definitions !== void 0 && !definitions.has(relation)) throw new Error(`Relation "${formatRelationName(relation.key, relation.name)}" is not part of the schema`);
-	if (isAggregateQuery(node)) return lowerAggregate(node);
-	const projections = lowerProjections(node.projections, definitions, db);
 	const guaranteedBy = node.guaranteed && relation !== void 0 ? formatRelationName(relation.key, relation.name) : void 0;
-	const page = node.offset !== void 0 && projections !== node.projections ? lowerPage(node, projections, positions, guaranteedBy) : void 0;
+	const page = node.offset !== void 0 && selected.some((field, index) => isPagedField(field, projections[index], orderBy)) ? lowerPage(node, projections, filters, orderBy, positions, guaranteedBy) : void 0;
 	if (page !== void 0) return page;
 	return Object.freeze({
 		kind: "select",
 		from: node.from,
 		joins: noJoins,
 		projections,
-		filters: node.filters,
-		orderBy: positions && node.orderBy.length > 0 ? sortByPositions(node.orderBy, projections) : node.orderBy,
+		filters,
+		orderBy: positions && orderBy.length > 0 ? sortByPositions(orderBy, projections) : orderBy,
 		limit: node.limit,
 		offset: node.offset,
 		rows: node.rows,
@@ -1438,17 +1526,38 @@ function lowerSelect(node, definitions, db, positions) {
 	});
 }
 /**
-* Lowers `node` with `projections` to a statement that evaluates its nested queries over the rows of a derived page.
+* Tells whether `field`, a field of a query lowered to `projection`, is a nested query that a page after an offset evaluates only over its rows: one that no sort key of `orderBy`, the lowered order, sorts by.
+*
+* The query evaluates a field that it sorts by, of an aggregate or of `exists`, for every row anyway.
+*/
+function isPagedField(field, projection, orderBy) {
+	if (!isNestedSelection(field)) return false;
+	const { expression } = projection;
+	return !orderBy.some((order) => order.expression === expression);
+}
+/** Rejects a query of a relation outside the definitions of `context`. */
+function checkRelation(node, context) {
+	const { relation } = node;
+	const { definitions } = context;
+	if (relation !== void 0 && definitions !== void 0 && !definitions.has(relation)) throw new Error(`Relation "${formatRelationName(relation.key, relation.name)}" is not part of the schema`);
+}
+/** Rejects a nested query bound to `db`, which the error names as `subject`, unless `db` is the `Db` of `context` or `undefined`. */
+function checkDb(db, context, subject) {
+	if (db !== void 0 && db !== context.db) throw new Error(context.db === void 0 ? `${subject} is bound to a Db, so only that Db can compile the query` : `${subject} is bound to another Db`);
+}
+/**
+* Lowers `node` with `projections`, `filters`, and `orderBy`, the lowered parts of the node, to a statement that evaluates its nested queries, apart from those that it sorts by, over the rows of a derived page.
 * The derived source applies the filters, the order, the limit, and the offset, and replaces the occurrence of the table.
 *
-* It returns `undefined` when a nested query holds a SQL fragment that refers to a column of the table outside the queries nested in the fragment.
+* It returns `undefined` when a nested query that it evaluates over the rows of the page holds a SQL fragment that refers to a column of the table outside the queries nested in the fragment.
 * Such a fragment may hold an aggregate of the query, which the limit and the offset apply after.
 *
 * The source selects the columns of the table that the fields and the nested queries of the query read, under their keys, and the other scalar fields of the query, which it evaluates before the limit and the offset as the query would, such as a window function over all its rows.
+* A field of an aggregate or of `exists` that the query sorts by is such a scalar field: the order needs its value for every row.
 * A column that no field reads stays out of the source, which could not select it beside an aggregate of a SQL fragment, such as `count(*)`.
 * The order of a derived source does not carry into the query that reads it, so the statement sorts the rows of the page again by the sort keys of the source, by positions when `positions` is set.
 */
-function lowerPage(node, projections, positions, guaranteedBy) {
+function lowerPage(node, projections, filters, orderBy, positions, guaranteedBy) {
 	const { from } = node;
 	const columnKeys = /* @__PURE__ */ new Set();
 	const fields = [];
@@ -1456,7 +1565,7 @@ function lowerPage(node, projections, positions, guaranteedBy) {
 	for (let index = 0; index < projections.length; index++) {
 		const { expression } = projections[index];
 		let key;
-		if (isNestedSelection(node.projections[index])) {
+		if (isPagedField(node.projections[index], projections[index], orderBy)) {
 			if (holdsFragmentOfSource(expression, from)) return;
 			collectColumnKeys(expression, from, columnKeys);
 		} else if (expression.kind === "column" && expression.source === from) columnKeys.add(expression.key);
@@ -1486,8 +1595,8 @@ function lowerPage(node, projections, positions, guaranteedBy) {
 		from,
 		joins: noJoins,
 		projections: sourced,
-		filters: node.filters,
-		orderBy: node.orderBy,
+		filters,
+		orderBy,
 		limit: node.limit,
 		offset: node.offset,
 		rows: "many",
@@ -1523,13 +1632,14 @@ function lowerPage(node, projections, positions, guaranteedBy) {
 	});
 }
 /** Lowers an aggregate query to a statement of the value of its aggregate over the rows that its filters, limit, and offset choose. */
-function lowerAggregate(node) {
+function lowerAggregate(node, context) {
 	const field = node.projections[0];
 	const aggregate = field.expression;
+	const orderBy = lowerOrder(node.orderBy, context);
 	let from = node.from;
-	let filters = node.filters;
-	let args = aggregate.arguments;
-	let order = field.ordered ? node.orderBy : noOrder;
+	let filters = lowerFilters(node.filters, context);
+	let args = lowerEach(aggregate.arguments, context, lowerExpression);
+	let order = field.ordered ? orderBy : noOrder;
 	const counted = aggregate === countProjection.expression;
 	if (node.limit !== void 0 || node.offset !== void 0 || !counted && !refersToSource(args[0], node.from)) {
 		const projections = [];
@@ -1543,8 +1653,8 @@ function lowerAggregate(node) {
 			from: node.from,
 			joins: noJoins,
 			projections,
-			filters: node.filters,
-			orderBy: counted ? noOrder : node.orderBy,
+			filters,
+			orderBy: counted ? noOrder : orderBy,
 			limit: node.limit,
 			offset: node.offset,
 			rows: "many",
@@ -1571,7 +1681,7 @@ function lowerAggregate(node) {
 		arguments: args,
 		orderBy: order
 	});
-	const { fallbacks } = field;
+	const fallbacks = lowerEach(field.fallbacks, context, lowerExpression);
 	let value = call;
 	if (fallbacks.length > 0) {
 		const values = [call];
@@ -1607,12 +1717,15 @@ function refersToSource(node, source) {
 		case "param":
 		case "boolean":
 		case "values":
+		case "nestedQuery":
 		case "tableName":
 		case "subquery":
-		case "exists": return false;
+		case "exists":
+		case "textSubquery": return false;
 		case "cast":
 		case "not":
-		case "isNull": return refersToSource(node.operand, source);
+		case "isNull":
+		case "inQuery": return refersToSource(node.operand, source);
 		case "and":
 		case "or": return node.operands.some((operand) => refersToSource(operand, source));
 		case "comparison": return refersToSource(node.left, source) || refersToSource(node.right, source);
@@ -1622,13 +1735,57 @@ function refersToSource(node, source) {
 		default: return node;
 	}
 }
+/** Lowers a query of `exists` to `EXISTS` of the rows that its filters, limit, and offset choose. */
+function lowerExists(node, context) {
+	checkRelation(node, context);
+	return createNode({
+		kind: "exists",
+		query: Object.freeze({
+			kind: "select",
+			from: node.from,
+			joins: noJoins,
+			projections: noProjections,
+			filters: lowerFilters(node.filters, context),
+			orderBy: noOrder,
+			limit: node.limit,
+			offset: node.offset,
+			rows: "many",
+			value: false,
+			guaranteedBy: void 0
+		})
+	});
+}
+/** Lowers a query of `exists` to a statement without a source of one row of `EXISTS` of its rows. */
+function selectExists(node, context) {
+	return Object.freeze({
+		kind: "select",
+		from: void 0,
+		joins: noJoins,
+		projections: [projectExists(node.projections[0].key, node, context)],
+		filters: noFilters,
+		orderBy: noOrder,
+		limit: void 0,
+		offset: void 0,
+		rows: node.rows,
+		value: true,
+		guaranteedBy: void 0
+	});
+}
+/** Creates the projection of `EXISTS` of the rows of `node`, a query of `exists`, under `key`, decoded by the type of the projection of `exists`. */
+function projectExists(key, node, context) {
+	return Object.freeze({
+		key,
+		expression: lowerExists(node, context),
+		type: node.projections[0].type
+	});
+}
 /** Lowers a query of `$select` to a statement without a source, which returns one row of its fields. */
-function lowerRecord(node, definitions, db) {
+function lowerRecord(node, context) {
 	return Object.freeze({
 		kind: "select",
 		from: void 0,
 		joins: noJoins,
-		projections: lowerProjections(node.projections, definitions, db),
+		projections: lowerProjections(node.projections, context),
 		filters: noFilters,
 		orderBy: noOrder,
 		limit: void 0,
@@ -1639,23 +1796,40 @@ function lowerRecord(node, definitions, db) {
 	});
 }
 /**
-* Lowers the fields of a query to projections, packing the rows of each nested query into the value of its field, or selecting the value of an aggregate query; checks them as `lowerQuery` does.
+* Lowers the fields of a query to projections, packing the rows of each nested query into the value of its field, or selecting the value of an aggregate query or `EXISTS` of a query of `exists`, and replacing the queries in the expressions of the other fields; checks them as `lowerQuery` does.
 *
-* Without nested queries, it returns `selected` itself.
+* Without queries, it returns `selected` itself.
 */
-function lowerProjections(selected, definitions, db) {
+function lowerProjections(selected, context) {
 	let lowered;
 	for (let index = 0; index < selected.length; index++) {
 		const field = selected[index];
+		let projection;
 		if (isNestedSelection(field)) {
-			if (field.db !== void 0 && field.db !== db) throw new Error(db === void 0 ? `Selected field "${field.key}" is bound to a Db, so only that Db can compile the query` : `Selected field "${field.key}" is bound to another Db`);
-			lowered ??= selected.slice(0, index);
-			const query = lowerSelect(field.query, definitions, db, false);
-			lowered.push(isAggregateQuery(field.query) ? projectAggregateValue(field.key, query) : projectRows(field.key, query));
-		} else if (lowered !== void 0) lowered.push(field);
+			checkDb(field.db, context, `Selected field "${field.key}"`);
+			projection = projectQuery(field.key, field.query, context);
+		} else {
+			const expression = lowerExpression(field.expression, context);
+			projection = expression === field.expression ? field : Object.freeze({
+				key: field.key,
+				expression,
+				type: field.type
+			});
+		}
+		if (lowered !== void 0) lowered.push(projection);
+		else if (projection !== field) {
+			lowered = selected.slice(0, index);
+			lowered.push(projection);
+		}
 	}
 	return lowered ?? selected;
 }
+/** Creates the projection of the value of `node`, a nested query, under `key`: `EXISTS` of a query of `exists`, the value of an aggregate query, or the packed rows of another query. */
+function projectQuery(key, node, context) {
+	if (isExistsQuery(node)) return projectExists(key, node, context);
+	const query = lowerSelect(node, context, false);
+	return isAggregateQuery(node) ? projectAggregateValue(key, query) : projectRows(key, query);
+}
 /** Creates the projection of the value of `query`, the statement of an aggregate query, under `key`, selected as a scalar subquery and decoded by the type of the aggregate. */
 function projectAggregateValue(key, query) {
 	return Object.freeze({
@@ -1667,6 +1841,176 @@ function projectAggregateValue(key, query) {
 		type: query.projections[0].type
 	});
 }
+/** Lowers the filters of a query, replacing the queries in their expressions; without queries, it returns `filters` itself. */
+function lowerFilters(filters, context) {
+	const { relation, scope, user } = filters;
+	const loweredRelation = relation === void 0 ? void 0 : lowerExpression(relation, context);
+	const loweredScope = scope === void 0 ? void 0 : lowerExpression(scope, context);
+	const loweredUser = user === void 0 ? void 0 : lowerExpression(user, context);
+	if (loweredRelation === relation && loweredScope === scope && loweredUser === user) return filters;
+	const lowered = {};
+	if (loweredRelation !== void 0) lowered.relation = loweredRelation;
+	if (loweredScope !== void 0) lowered.scope = loweredScope;
+	if (loweredUser !== void 0) lowered.user = loweredUser;
+	return Object.freeze(lowered);
+}
+/**
+* Lowers the sort keys of a query, replacing the queries in their expressions; without queries, it returns `orderBy` itself.
+*
+* A sort key of a field of `selected`, the fields of the query, takes the expression of its projection among `projections`, the lowered fields, so that the statement still finds the projection that has its value.
+* A field of an aggregate or of `exists` is identified by the node of its reference, which holds the field.
+*/
+function lowerOrder(orderBy, context, selected, projections) {
+	let lowered;
+	for (let index = 0; index < orderBy.length; index++) {
+		const order = orderBy[index];
+		const { expression } = order;
+		const position = selected === void 0 || projections === void 0 || projections === selected ? -1 : selected.findIndex((field) => isFieldValue(field, expression));
+		const sorted = position === -1 ? lowerExpression(expression, context) : projections[position].expression;
+		if (lowered === void 0 && sorted === expression) continue;
+		lowered ??= orderBy.slice(0, index);
+		lowered.push(sorted === expression ? order : Object.freeze({
+			expression: sorted,
+			direction: order.direction,
+			nulls: order.nulls
+		}));
+	}
+	return lowered ?? orderBy;
+}
+/** Tells whether the sort expression `expression` is the value of `field`: its expression, or for a field of an aggregate or of `exists`, the node of its reference in the callback of `orderBy`. */
+function isFieldValue(field, expression) {
+	return isNestedSelection(field) ? expression.kind === "nestedQuery" && expression.field === field : field.expression === expression;
+}
+/**
+* Lowers an expression, replacing each query in it and checking the query as a nested query.
+* A query of `exists`, such as in a condition, becomes `EXISTS` of its rows, another query of one value a scalar subquery of its value, the query of the values of `IN` its statement, and another query in SQL text its statement in parentheses.
+*
+* It returns `node` itself when it holds no query, and creates only the nodes that hold one.
+*/
+function lowerExpression(node, context) {
+	switch (node.kind) {
+		case "column":
+		case "param":
+		case "boolean":
+		case "values":
+		case "tableName":
+		case "subquery":
+		case "exists":
+		case "textSubquery": return node;
+		case "nestedQuery": return lowerNestedQuery(node, context);
+		case "cast": {
+			const operand = lowerExpression(node.operand, context);
+			return operand === node.operand ? node : createNode({
+				kind: "cast",
+				operand,
+				type: node.type
+			});
+		}
+		case "not": {
+			const operand = lowerExpression(node.operand, context);
+			return operand === node.operand ? node : createNode({
+				kind: "not",
+				operand
+			});
+		}
+		case "isNull": {
+			const operand = lowerExpression(node.operand, context);
+			return operand === node.operand ? node : createNode({
+				kind: "isNull",
+				operand
+			});
+		}
+		case "and":
+		case "or": {
+			const operands = lowerEach(node.operands, context, lowerExpression);
+			return operands === node.operands ? node : createNode({
+				kind: node.kind,
+				operands
+			});
+		}
+		case "comparison": {
+			const left = lowerExpression(node.left, context);
+			const right = lowerExpression(node.right, context);
+			return left === node.left && right === node.right ? node : createNode({
+				kind: "comparison",
+				operator: node.operator,
+				left,
+				right
+			});
+		}
+		case "in": {
+			const operand = lowerExpression(node.operand, context);
+			const list = lowerEach(node.list, context, lowerExpression);
+			return operand === node.operand && list === node.list ? node : createNode({
+				kind: "in",
+				operand,
+				list
+			});
+		}
+		case "inQuery": {
+			const operand = lowerExpression(node.operand, context);
+			const query = node.query.kind === "nestedQuery" ? lowerQueryOfValues(node.query, context) : node.query;
+			return operand === node.operand && query === node.query ? node : createNode({
+				kind: "inQuery",
+				operand,
+				query
+			});
+		}
+		case "raw": {
+			const values = lowerEach(node.values, context, lowerExpression);
+			return values === node.values ? node : createNode({
+				kind: "raw",
+				fragments: node.fragments,
+				values
+			});
+		}
+		case "aggregate": {
+			const args = lowerEach(node.arguments, context, lowerExpression);
+			const orderBy = lowerOrder(node.orderBy, context);
+			return args === node.arguments && orderBy === node.orderBy ? node : createNode({
+				kind: "aggregate",
+				name: node.name,
+				distinct: node.distinct,
+				arguments: args,
+				orderBy
+			});
+		}
+		default: return node;
+	}
+}
+/**
+* Lowers a query in an expression to `EXISTS` of the rows of a query of `exists`, to a scalar subquery of the value of another query of one value, or to its statement in parentheses for a query of records or of rows `many`, which only SQL text holds.
+*
+* In SQL text, a query of `exists` stays `EXISTS` rather than a subquery of its value, so that PostgreSQL can join its rows in a condition, as a semi-join.
+*/
+function lowerNestedQuery(node, context) {
+	checkDb(node.db, context, "A query in an expression");
+	const { query } = node;
+	if (isExistsQuery(query)) return lowerExists(query, context);
+	return createNode({
+		kind: query.value && query.rows !== "many" ? "subquery" : "textSubquery",
+		query: lowerSelect(query, context, false)
+	});
+}
+/** Lowers the query of the values of `IN` to its statement, whatever its rows. */
+function lowerQueryOfValues(node, context) {
+	checkDb(node.db, context, "A query in an expression");
+	return lowerSelect(node.query, context, false);
+}
+/** Lowers each of `items` with `lower`; when none changes, it returns `items` itself. */
+function lowerEach(items, context, lower) {
+	let lowered;
+	for (let index = 0; index < items.length; index++) {
+		const item = items[index];
+		const result = lower(item, context);
+		if (lowered !== void 0) lowered.push(result);
+		else if (result !== item) {
+			lowered = items.slice(0, index);
+			lowered.push(result);
+		}
+	}
+	return lowered ?? items;
+}
 // src/query/kind.ts
 /** `then` of every bound query, which executes the query on its `Db`. */
 function executeOnAwait(onFulfilled, onRejected) {
@@ -1689,7 +2033,7 @@ const noContext = /* @__PURE__ */ Object.freeze({ relations: /* @__PURE__ */ Obj
 function createColumnRefs(source) {
 	return addColumns({}, source);
 }
-/** Creates the references of the callback of `select` over `source`: its columns, and the relations of `context`. */
+/** Creates the references of the callbacks of `select`, `where`, and `orderBy` over `source`: its columns, and the relations of `context`. */
 function createSelectionRefs(source, context) {
 	return Object.defineProperties(addColumns({}, source), context.relations);
 }
@@ -1749,9 +2093,9 @@ function matchValue(source, column, type, value) {
 	return toNode(predicate);
 }
 // src/query/filters.ts
-/** Creates query filters with the filter of `where` over `source` combined with `AND` with the user filters of `filters`. */
-function addUserFilter(filters, filter, source) {
-	const predicate = resolveValues(toConditionNode(typeof filter === "function" ? filter(createColumnRefs(source)) : filter), source);
+/** Creates query filters with the filter of `where` over `source` with the relations of `context` combined with `AND` with the user filters of `filters`. */
+function addUserFilter(filters, filter, source, context) {
+	const predicate = resolveValues(toConditionNode(typeof filter === "function" ? filter(createSelectionRefs(source, context)) : filter), source);
 	const { user } = filters;
 	return Object.freeze({
 		...filters,
@@ -1843,29 +2187,29 @@ var OrderingObject = class {
 		Object.freeze(this);
 	}
 };
-/** Sorts by `expression` in ascending order, in the callback of `orderBy`. */
-function asc(expression) {
-	return orderBy(expression, "asc");
+/** Sorts by `value`, an expression or a query of one value, in ascending order, in the callback of `orderBy`. */
+function asc(value) {
+	return orderBy(value, "asc");
 }
-/** Sorts by `expression` in descending order, in the callback of `orderBy`. */
-function desc(expression) {
-	return orderBy(expression, "desc");
+/** Sorts by `value`, an expression or a query of one value, in descending order, in the callback of `orderBy`. */
+function desc(value) {
+	return orderBy(value, "desc");
 }
-/** Sorts by `expression` in `direction`, such as `"desc nulls last"`, in the callback of `orderBy`. */
-function orderBy(expression, direction) {
-	if (!isExpression(expression)) throw new TypeError("A sort key must be an expression");
-	return new OrderingObject(createOrderNode(toNode(expression), direction));
+/** Sorts by `value`, an expression or a query of one value, in `direction`, such as `"desc nulls last"`, in the callback of `orderBy`. */
+function orderBy(value, direction) {
+	if (!isOperandSource(value)) throw new TypeError("A sort key must be an expression or a query of one value");
+	return new OrderingObject(createOrderNode(value[operandNode](), direction));
 }
 /**
 * Creates the order of `node` with the sort keys of the arguments of `orderBy` after its own.
 *
-* `args` are column keys and objects of columns with directions, or a callback that receives the columns and the selected fields and returns one sort key or an array of them.
+* `args` are column keys and objects of columns with directions, or a callback that receives the columns with the relations of `context` and the selected fields, and returns one sort key or an array of them.
 */
-function addOrder(node, args) {
+function addOrder(node, context, args) {
 	const order = node.orderBy.slice();
 	const first = args[0];
 	if (typeof first === "function") {
-		const terms = first(createColumnRefs(node.from), createSelectedRefs(node));
+		const terms = first(createSelectionRefs(node.from, context), createSelectedRefs(node));
 		if (Array.isArray(terms)) for (const term of terms) order.push(readTerm(term));
 		else order.push(readTerm(terms));
 		return order;
@@ -1877,11 +2221,15 @@ function addOrder(node, args) {
 	} else throw new TypeError("orderBy takes column keys and objects of columns with directions, or a callback");
 	return order;
 }
-/** Creates the sort key node of a sort key returned by the callback of `orderBy`. */
+/**
+* Creates the sort key node of a sort key returned by the callback of `orderBy`.
+*
+* A query is converted by the method of `operandNode`, which rejects a query other than of one value.
+*/
 function readTerm(term) {
 	if (term instanceof OrderingObject) return term[orderingNode];
-	if (isExpression(term)) return createOrderNode(toNode(term), "asc");
-	throw new TypeError("The callback of orderBy must return expressions, or sort keys of asc, desc, and orderBy");
+	if (isOperandSource(term)) return createOrderNode(term[operandNode](), "asc");
+	throw new TypeError("The callback of orderBy must return expressions, queries of one value, or sort keys of asc, desc, and orderBy");
 }
 /** Creates the sort key node of `expression` in `direction`, an `OrderDirection` checked at runtime. */
 function createOrderNode(expression, direction) {
@@ -1906,6 +2254,7 @@ function createColumnNode(source, key) {
 * Creates the references of the callback of `orderBy` to the fields selected by `node`.
 *
 * Each is an expression over the node of its projection, so that a sort key of it is the projection itself.
+* A field of an aggregate or of `exists` is an expression of its query that holds the field, by which lowering finds the projection of the field.
 */
 function createSelectedRefs(node) {
 	const { projections } = node;
@@ -1913,13 +2262,15 @@ function createSelectedRefs(node) {
 	const refs = {};
 	for (const projection of projections) {
 		const { key } = projection;
-		if (isNestedSelection(projection)) Object.defineProperty(refs, key, {
-			get() {
-				throw new Error(`Field "${key}" holds a nested query and cannot be sorted by`);
-			},
-			enumerable: true
-		});
-		else refs[key] = toSelectedExpression(projection);
+		if (isNestedSelection(projection)) {
+			if (isSelectedAsValue(projection.query)) refs[key] = toQueryExpression(projection);
+			else Object.defineProperty(refs, key, {
+				get() {
+					throw new Error(`Field "${key}" holds nested rows and cannot be sorted by`);
+				},
+				enumerable: true
+			});
+		} else refs[key] = toSelectedExpression(projection);
 	}
 	return refs;
 }
@@ -1927,6 +2278,16 @@ function createSelectedRefs(node) {
 function toSelectedExpression(projection) {
 	return toExpression(projection.expression, projection.type);
 }
+/** Creates an expression of the value of `field`, a selected aggregate query or query of `exists`, with the type of its value. */
+function toQueryExpression(field) {
+	const { query } = field;
+	return toExpression(createNode({
+		kind: "nestedQuery",
+		query,
+		db: field.db,
+		field
+	}), query.projections[0].type);
+}
 // src/query/pagination.ts
 /** Creates the parameter of the number of rows of `limit` or `offset`, named by `method`, of query `node`, rejecting a query of one row and a count that is not a non-negative safe integer. */
 function createPageCount(node, method, count) {
@@ -1941,7 +2302,9 @@ function createPageCount(node, method, count) {
 /** Creates the hint of the error of `limit` or `offset` of query `node` of one row: the method to call them before, if any. */
 function createPaginationHint(node) {
 	if (node.relation?.kind === "one") return "";
-	return isAggregateQuery(node) ? "; call it before count or another aggregate to aggregate the rows of a page" : "; call it before take or get";
+	if (isAggregateQuery(node)) return "; call it before count or another aggregate to aggregate the rows of a page";
+	if (isExistsQuery(node)) return "; call it before exists to check the rows of a page";
+	return "; call it before take or get";
 }
 // src/query/select.ts
 /**
@@ -2032,13 +2395,21 @@ var SelectQuery = class SelectQuery {
 	stringAgg(arg, delimiter) {
 		return this.aggregateBy("stringAgg", arg, delimiter);
 	}
+	exists() {
+		this.rejectAggregate("exists");
+		return this.deriveAggregate(getExistsProjection());
+	}
 	coalesce(fallback) {
 		const { node } = this;
 		if (!node.value) throw new Error("coalesce applies only to a query of values, such as one made by get, pluck, or an aggregate");
 		return this.derive({ projections: [coalesceValue(node.projections[0], fallback)] });
 	}
+	expr() {
+		const value = this[operandNode]();
+		return toExpression(value, this.node.projections[0].type);
+	}
 	orderBy(...args) {
-		return this.derive({ orderBy: addOrder(this.node, args) });
+		return this.derive({ orderBy: addOrder(this.node, this.context, args) });
 	}
 	limit(count) {
 		return this.derive({ limit: createPageCount(this.node, "limit", count) });
@@ -2079,6 +2450,34 @@ var SelectQuery = class SelectQuery {
 	toSQL(options) {
 		return compileToSQL(this, options);
 	}
+	/**
+	* Returns the node of the query as an operand of an expression, which lowering replaces with a scalar subquery of its value, or with `EXISTS` of its rows for a query of `exists`.
+	*
+	* It rejects a query of records or of rows `many`, which `ScalarQuery` rejects in types.
+	*/
+	[operandNode]() {
+		const { node } = this;
+		if (!node.value || node.rows === "many") throw new TypeError("An expression takes a query of one value, such as of get, an aggregate, or exists, not a query of records or of an array");
+		return createNode({
+			kind: "nestedQuery",
+			query: node,
+			db: this.db
+		});
+	}
+	/**
+	* Returns the node of the query as the values of `in`, which lowering replaces with its statement.
+	*
+	* It rejects a query of records, which `ValuesQuery` rejects in types.
+	*/
+	[valuesQueryNode]() {
+		const { node } = this;
+		if (!node.value) throw new TypeError("in takes a query of values, such as of pluck, not a query of records");
+		return createNode({
+			kind: "nestedQuery",
+			query: node,
+			db: this.db
+		});
+	}
 	/** Creates a query of the same kind and `Db` with the node changes applied. */
 	derive(changes) {
 		return new SelectQuery(this.table, Object.freeze({
@@ -2098,7 +2497,7 @@ var SelectQuery = class SelectQuery {
 		}
 		return this.derive(changes);
 	}
-	/** Creates the query of the value of `projection`, an aggregate over the rows of this query, which always returns one row. */
+	/** Creates the query of the value of `projection`, of an aggregate or of `exists` over the rows of this query, which always returns one row. */
 	deriveAggregate(projection) {
 		return this.derive({
 			projections: [projection],
@@ -2116,7 +2515,7 @@ var SelectQuery = class SelectQuery {
 	addFilter(filter) {
 		const { node } = this;
 		return {
-			filters: addUserFilter(node.filters, filter, node.from),
+			filters: addUserFilter(node.filters, filter, node.from, this.context),
 			rows: toFilteredRows(node.rows, node.value, node.guaranteed),
 			guaranteed: false
 		};
@@ -2141,9 +2540,11 @@ var SelectQuery = class SelectQuery {
 		this.rejectAggregate(method);
 		throw new Error(`${method} cannot be used after get or pluck; call get or pluck to replace the value`);
 	}
-	/** Rejects `method`, which replaces the value or the selection, on a query made by an aggregate method. */
+	/** Rejects `method`, which replaces the value or the selection, on a query made by an aggregate method or `exists`. */
 	rejectAggregate(method) {
-		if (isAggregateQuery(this.node)) throw new Error(`${method} cannot be used after an aggregate`);
+		const { node } = this;
+		if (isAggregateQuery(node)) throw new Error(`${method} cannot be used after an aggregate`);
+		if (isExistsQuery(node)) throw new Error(`${method} cannot be used after exists`);
 	}
 };
 /**
@@ -2230,6 +2631,10 @@ var SqlQuery = class SqlQuery {
 	toSQL() {
 		return this.db.$compile(this);
 	}
+	/** Rejects the query as an operand of an expression, which takes a query of one value of a table. */
+	[operandNode]() {
+		throw new TypeError("An expression takes a query of one value of a table, such as of get, an aggregate, or exists, not a query of $query");
+	}
 	/** Creates a query of the same `Db` with the node changes applied. */
 	derive(changes) {
 		return new SqlQuery(Object.freeze({
@@ -2374,6 +2779,10 @@ var MutationQuery = class MutationQuery {
 	toSQL(options) {
 		return compileToSQL(this, options);
 	}
+	/** Rejects the query as an operand of an expression, which takes a query of one value of a table. */
+	[operandNode]() {
+		throw new TypeError("An expression takes a query of one value of a table, such as of get, an aggregate, or exists, not a query of insert, update, or delete");
+	}
 	/** Creates a mutation of the same kind and `Db` with the node changes applied. */
 	derive(changes) {
 		return new MutationQuery(this.table, Object.freeze({
@@ -2486,12 +2895,14 @@ function projectValue(source, arg, method) {
 	return projectExpression("value", value, type);
 }
 /**
-* Creates the projection of the value of `field`, the only projection of a query of values, whose `NULL` `fallback` replaces: a value that the type of the field encodes, or an expression.
+* Creates the projection of the value of `field`, the only projection of a query of values, whose `NULL` `fallback` replaces: a value that the type of the field encodes, an expression, or a query of one value.
 *
 * The projection of an aggregate keeps its call, which lowering builds, and adds the fallback after its earlier ones.
+* The projection of `exists` stays as it is, since `EXISTS` is never `NULL`.
 */
 function coalesceValue(field, fallback) {
 	if (fallback === null || fallback === void 0) throw new TypeError(`coalesce takes a value other than ${String(fallback)}`);
+	if (isExistsProjection(field)) return field;
 	const value = toValueNode(fallback, field.type);
 	if (isAggregateProjection(field)) return addFallback(field, value);
 	return Object.freeze({
@@ -2568,6 +2979,10 @@ var RecordQuery = class {
 	toSQL(options) {
 		return compileToSQL(this, options);
 	}
+	/** Rejects the query as an operand of an expression, which takes a query of one value of a table. */
+	[operandNode]() {
+		throw new TypeError("An expression takes a query of one value of a table, such as of get, an aggregate, or exists, not a query of $select");
+	}
 };
 /**
 * Starts the query of `$select` of `selection`, an object of expressions and queries by key, bound to `db` when given.
@@ -2699,6 +3114,26 @@ function sql(first, ...values) {
 	if (!isType(first)) throw new TypeError("sql() accepts a type, not a column");
 	return (strings, ...values) => createFragment(strings, values, first);
 }
+/**
+* Creates a SQL fragment of a quoted name, such as of a table or a column known only at runtime, for the templates of `sql`, of `$query` and `$script` of a `Db`, and of `query` and `script` of a `Database`.
+*
+* Several names make a qualified name, such as `identifier(schema, table)` for `"schema"."table"`.
+* The fragment has no parameters, so a script takes it.
+* The name is not qualified by the PostgreSQL schema of the statement.
+*/
+function identifier(...names) {
+	let text = "";
+	for (const name of names) {
+		if (typeof name !== "string" || name === "") throw new TypeError("identifier() takes names as non-empty strings");
+		text += (text === "" ? "" : ".") + quoteIdentifier(name);
+	}
+	if (text === "") throw new TypeError("identifier() takes at least one name");
+	return toExpression(createNode({
+		kind: "raw",
+		fragments: [text],
+		values: []
+	}));
+}
 function param(type, value) {
 	if (!isType(type) && !isExpression(type)) throw new TypeError("param() accepts a type or an expression, not a column");
 	if (isExpression(type)) {
@@ -2720,9 +3155,12 @@ function createFragment(strings, values, type) {
 	return toExpression(toRawSqlNode(strings, values), type);
 }
 /**
-* Creates the node of the SQL of a template: interpolated expressions keep their nodes, a query of a table without clauses becomes the name of the table, qualified by the PostgreSQL schema of the statement, and other values become query parameters.
+* Creates the node of the SQL of a template, whose interpolations stay structured nodes.
 *
-* It rejects other queries, which a parameter would encode as text.
+* An interpolated expression keeps its node, and a query of a table without clauses becomes the name of the table, qualified by the PostgreSQL schema of the statement.
+* Another query of a table becomes a query in an expression, which lowering replaces with its SQL.
+* Other values become query parameters.
+* It rejects the other queries, which a parameter would encode as text.
 */
 function toRawSqlNode(strings, values) {
 	const nodes = [];
@@ -2736,14 +3174,18 @@ function toRawSqlNode(strings, values) {
 /** Returns the node of a value interpolated into SQL, as `toRawSqlNode` takes it. */
 function toInterpolatedNode(value) {
 	if (value instanceof SelectQuery) {
-		if (!isTableQuery(value.node)) throw new TypeError("sql takes a query of a table without clauses, such as db.form, as the name of the table, not a query with clauses");
-		return createNode({
+		const { node } = value;
+		return isTableQuery(node) ? createNode({
 			kind: "tableName",
 			table: value.table,
 			db: value.db
+		}) : createNode({
+			kind: "nestedQuery",
+			query: node,
+			db: value.db
 		});
 	}
-	if (value instanceof RecordQuery || value instanceof MutationQuery || value instanceof SqlQuery) throw new TypeError("sql takes a query of a table without clauses, such as db.form, as the name of the table, not another query");
+	if (value instanceof RecordQuery || value instanceof MutationQuery || value instanceof SqlQuery) throw new TypeError("sql takes a query of a table, such as db.form or a query of its records, not a query of $select, a mutation, or a query of SQL text");
 	return toValueNode(value);
 }
 // src/execution/db.ts
@@ -2777,10 +3219,13 @@ function bindSchema(schema, database, options = {}) {
 		async $script(script, ...values) {
 			if (typeof script === "string") return database.script(script);
 			const { text, parameters } = compile(startSqlQuery(toRawSqlNode(script, values), db));
-			if (parameters.length > 0) throw new Error("A script takes no values, since it has no parameters; interpolate only tables and sql fragments without values");
+			if (parameters.length > 0) throw new Error("A script has no parameters, so it takes no values, also in the queries and sql fragments that it interpolates");
 			return database.script(text);
 		},
-		$transaction: (callback, options) => database.transaction(callback, options)
+		$transaction: (callback, options) => database.transaction(callback, options),
+		$ensureTransaction: (callback) => database.ensureTransaction(callback),
+		$isInTransaction: () => database.isInTransaction(),
+		$lock: (key) => database.lock(key)
 	};
 	const contexts = createQueryContexts(Object.keys(schema.$tables), relations);
 	const db = defineEntries(methods, schema.$tables, (key) => bindQuery(startQuery(schema.$tables[key], contexts[key]), db));
@@ -2851,6 +3296,27 @@ var TransactionCoordinator = class {
 		return this.test ? Promise.reject(new Error(describeOutsideTest("start a transaction"))) : this.#runRoot(callback, true, void 0, settings);
 	}
 	/**
+	* Runs `callback` in the current transaction, or in a new transaction outside of one.
+	*
+	* Joining starts no savepoint, so a rejection of `callback` does not undo its changes.
+	* It rejects without calling `callback` when the current level accepts no statements, as a nested transaction would.
+	*/
+	async ensureTransaction(callback) {
+		const level = this.#storage.getStore();
+		if (!level?.inTransaction) return this.transaction(callback);
+		const unavailable = createUnavailableError(level, "join the transaction");
+		if (unavailable) throw unavailable;
+		return callback();
+	}
+	/**
+	* Tells whether the current async context runs in a transaction of `transaction`.
+	*
+	* A test transaction and the seed of a test fixture are not transactions, unless they run inside one, so that code under test behaves as in production.
+	*/
+	isInTransaction() {
+		return this.#storage.getStore()?.inTransaction ?? false;
+	}
+	/**
 	* Runs `callback` in a transaction that always rolls back, on a coordinator created for tests.
 	*
 	* Inside a transaction, it runs `callback` in a savepoint nested in it that always rolls back.
@@ -3017,7 +3483,7 @@ var TransactionCoordinator = class {
 	*/
 	async #seedFixture(fixture, seed) {
 		try {
-			return await this.#run(await this.#startNested(fixture), seed, true);
+			return await this.#run(await this.#startNested(fixture, false), seed, true);
 		} catch (error) {
 			return { rejection: { error } };
 		}
@@ -3069,7 +3535,7 @@ var TransactionCoordinator = class {
 		} catch (error) {
 			throw (await releaseConnection(connection, { error }, { error })).error;
 		}
-		return createLevel(connection, void 0);
+		return createLevel(connection, void 0, false);
 	}
 	/**
 	* Starts a nested level of a test fixture, preempting its active one.
@@ -3085,12 +3551,12 @@ var TransactionCoordinator = class {
 		const unavailable = createUnavailableError(fixture, "start a level of the test fixture");
 		if (unavailable) throw suppressAbortReason(unavailable, signal);
 		signal?.throwIfAborted();
-		return this.#startNested(fixture, signal);
+		return this.#startNested(fixture, false, signal);
 	}
 	async #runRoot(callback, commits, signal, settings) {
 		const connection = await (signal ? acquireUnlessAborted(this.driver, signal) : this.driver.acquire());
 		if (signal?.aborted) throw (await releaseConnection(connection, void 0, { error: signal.reason })).error;
-		const level = createLevel(connection, void 0);
+		const level = createLevel(connection, void 0, commits);
 		let outcome;
 		try {
 			await connection.execute(beginStatement);
@@ -3114,16 +3580,17 @@ var TransactionCoordinator = class {
 	async #runNested(parent, callback, commits, signal, settings) {
 		const unavailable = createUnavailableError(parent, "start a nested transaction");
 		if (unavailable) throw unavailable;
-		return this.#runStarted(await this.#startNested(parent, signal, settings), callback, commits, signal);
+		return this.#runStarted(await this.#startNested(parent, commits, signal, settings), callback, commits, signal);
 	}
 	/**
 	* Reserves a nested level of `parent`, sends its `SAVEPOINT`, and applies its `settings`, rejecting when one of them fails.
 	*
+	* `transaction` tells whether the level is a transaction of `transaction` rather than a level of the test helpers.
 	* A level whose settings fail rolls back to its savepoint first.
 	* The failure suppresses the reason of `signal` when the signal aborted before it.
 	*/
-	async #startNested(parent, signal, settings) {
-		const level = createLevel(parent.connection, parent);
+	async #startNested(parent, transaction, signal, settings) {
+		const level = createLevel(parent.connection, parent, transaction);
 		parent.child = level;
 		try {
 			await level.connection.execute(createStatement(`SAVEPOINT ${getSavepointName(level)}`));
@@ -3210,11 +3677,12 @@ var TransactionCoordinator = class {
 const beginStatement = createStatement("BEGIN");
 const commitStatement = createStatement("COMMIT");
 const rollbackStatement = createStatement("ROLLBACK");
-function createLevel(connection, parent) {
+function createLevel(connection, parent, transaction) {
 	return {
 		connection,
 		parent,
 		depth: parent ? parent.depth + 1 : 0,
+		inTransaction: transaction || (parent?.inTransaction ?? false),
 		state: "starting",
 		child: void 0,
 		rollbackOnly: void 0,
@@ -3410,13 +3878,23 @@ function createDatabase({ driver, test }) {
 		script: (script, ...values) => typeof script === "string" ? coordinator.executeScript(script) : getTablelessDb().$script(script, ...values),
 		execute: (statement) => coordinator.execute(statement),
 		transaction: (callback, options) => coordinator.transaction(callback, options),
+		ensureTransaction: (callback) => coordinator.ensureTransaction(callback),
+		isInTransaction: () => coordinator.isInTransaction(),
+		async lock(key) {
+			if (!coordinator.isInTransaction()) throw new Error("Cannot take an advisory lock outside a transaction, where it would end with its statement; a test transaction alone does not count");
+			await coordinator.execute(createLockStatement(key));
+		},
 		close: () => coordinator.close(),
 		[Symbol.asyncDispose]: () => coordinator.close()
 	};
 	return database;
 }
+/** Creates the statement that takes a transaction-level advisory lock on a 64-bit hash of `key`. */
+function createLockStatement(key) {
+	return createStatement("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [key]);
+}
 // src/query/helper.ts
 function defineHelper(_table, helper) {
 	return (query, ...args) => requireDerived(query, helper(query, ...args), "The callback of a helper");
 }
-export { NotFoundError, RequiredRelationError, ResultDecodeError, and, asc, compare, createDatabase, createStatement, defineFilter, defineGenericOperator, defineHelper, defineSchema, defineTable, defineType, desc, equalityOperators, from, many, not, one, or, orderBy, orderingOperators, param, sql, textOperators };
+export { NotFoundError, RequiredRelationError, ResultDecodeError, and, asc, compare, createDatabase, createStatement, defineFilter, defineGenericOperator, defineHelper, defineSchema, defineTable, defineType, desc, equalityOperators, from, identifier, many, not, one, or, orderBy, orderingOperators, param, sql, textOperators };