kern-orm 0.6.0 → 0.7.0

package/dist/{database-CP4oapsQ.mjs → database-B7Kf5Q9X.mjs}

@@ -1,4 +1,4 @@
-import { B as noOrder, C as toNode, D as isType, E as defineType, F as createNode, H as oneNode, I as createSelectNode, L as falseNode, M as valuesQueryNode, O as Column, P as createList, R as noFilters, S as toFunctionOperandNode, T as getBooleanType, U as trueNode, V as noProjections, _ as isOperandSource, a as stringifyJson, b as toCastValueNode, d as orderingOperators, g as isExpression, h as getType, j as isEqualityCompatible, m as createIsNullNode, n as text, p as compareNodes, s as encodeBytea, v as operandNode, w as toValueNode, x as toExpression, y as toBooleanExpression, z as noJoins } from "./text-Cti9QLK7.mjs";
+import { B as noOrder, C as toNode, D as isType, E as defineType, F as createNode, H as oneNode, I as createSelectNode, L as falseNode, M as valuesQueryNode, O as Column, P as createList, R as noFilters, S as toFunctionOperandNode, T as getBooleanType, U as trueNode, V as noProjections, _ as isOperandSource, a as stringifyJson, b as toCastValueNode, d as orderingOperators, g as isExpression, h as getType, j as isEqualityCompatible, m as createIsNullNode, n as text, p as compareNodes, s as encodeBytea, v as operandNode, w as toValueNode, x as toExpression, y as toBooleanExpression, z as noJoins } from "./text-CIUxPWPl.mjs";
 import { types } from "node:util";
 import { AsyncLocalStorage } from "node:async_hooks";
 // src/ast/boolean.ts
@@ -648,11 +648,14 @@ function createTable(name, definitions, options, deriveColumnName) {
 		columns[key] = column;
 	}
 	if (deriveColumnName) nameColumns(name, columns, deriveColumnName);
+	const singleton = options?.singleton;
+	if (singleton !== void 0 && typeof singleton !== "boolean") throw new TypeError(`The singleton option of table "${name}" must be a boolean`);
 	return Object.freeze({
 		kind: "table",
 		name,
 		columns: Object.freeze(columns),
-		keys: defineKeys(name, columns, options)
+		keys: defineKeys(name, columns, options),
+		singleton: singleton === true
 	});
 }
 /**
@@ -731,8 +734,14 @@ function findColumn(table, key) {
 }
 /** Tells whether the columns of `table` under `columns` are exactly a key of it, primary or unique, in any order, as `IsKey` does in types. */
 function isKey(table, columns) {
+	return findKey(table, columns) !== void 0;
+}
+/** Returns the key of `table`, primary or unique, whose columns are exactly those under `columns` in any order, as `isKey` tells, or `undefined`. */
+function findKey(table, columns) {
 	const listed = new Set(columns);
-	return someKey(table, (key) => key.length === listed.size && isKeyAmong(key, listed));
+	const isListed = (key) => key.length === listed.size && isKeyAmong(key, listed);
+	const { primaryKey, unique } = table.keys;
+	return primaryKey !== void 0 && isListed(primaryKey) ? primaryKey : unique.find(isListed);
 }
 /** Tells whether the columns of `table` under `columns` include a key of it, primary or unique, as `ContainsKey` does in types. */
 function containsKey(table, columns) {
@@ -967,25 +976,20 @@ function compileStatement(node, options = {}, tables, db) {
 		}
 	}
 }
-/** Compiles a mutation, whose expressions see only the occurrence of its table, apart from the values of an insert, which see no source. */
+/** Compiles a mutation, whose expressions see the occurrence of its table, apart from the values of an insert, which see no source, and the values of `DO UPDATE SET`, which also see the row proposed for insertion as `excluded`. */
 function compileMutation(context, node) {
+	if (node.kind === "insert" && node.conflict?.update !== void 0) context.createAlias(excludedAlias);
 	const scope = declareSource(context, void 0, node.target);
 	const target = compileSource(context, void 0, scope);
 	let text;
 	switch (node.kind) {
 		case "insert":
-			text = `INSERT INTO ${target}${compileValues(context, node)}`;
+			text = `INSERT INTO ${target}${compileValues(context, node)}${compileConflict(context, scope, node)}`;
 			break;
-		case "update": {
-			text = `UPDATE ${target} SET`;
-			const { set } = node;
-			for (let index = 0; index < set.length; index++) {
-				const { key, value } = set[index];
-				text += `${index === 0 ? " " : ", "}${compileColumnName(node.target, key)} = ${compileExpression(context, scope, value)}`;
-			}
+		case "update":
+			text = `UPDATE ${target} SET${compileAssignments(context, scope, node.target, node.set)}`;
 			text += compileWhere(context, scope, node.filters);
 			break;
-		}
 		case "delete":
 			text = `DELETE FROM ${target}${compileWhere(context, scope, node.filters)}`;
 			break;
@@ -1016,7 +1020,41 @@ function compileValues(context, node) {
 	}
 	return text;
 }
-/** Compiles the physical name of the column of the table of `target` under `key`, as `SET` and the column list of an insert name it, without an alias. */
+/** Alias of the row proposed for insertion in `DO UPDATE` of `ON CONFLICT`, which PostgreSQL names `EXCLUDED`. */
+const excludedAlias = "excluded";
+/**
+* Compiles `ON CONFLICT` of an insert, which names the physical columns of its key, or the expression `(true)` of the unique index of a singleton table, or nothing for an insert without it.
+*
+* The values of `DO UPDATE SET` see the existing row in `scope`, the occurrence of the table of the insert, and the row proposed for insertion as `excluded`.
+*/
+function compileConflict(context, scope, node) {
+	const { conflict } = node;
+	if (conflict === void 0) return "";
+	const { target, update } = conflict;
+	let text = " ON CONFLICT";
+	if (target === "singleton") text += " ((true))";
+	else {
+		for (let index = 0; index < target.length; index++) text += `${index === 0 ? " (" : ", "}${compileColumnName(node.target, target[index])}`;
+		if (target.length > 0) text += ")";
+	}
+	if (update === void 0) return `${text} DO NOTHING`;
+	const excluded = {
+		source: update.excluded,
+		alias: excludedAlias,
+		outer: scope
+	};
+	return `${text} DO UPDATE SET${compileAssignments(context, excluded, node.target, update.set)}`;
+}
+/** Compiles the assignments of `SET` of an update or of `DO UPDATE` to the columns of the table of `target`, whose values see the sources of `scope`. */
+function compileAssignments(context, scope, target, set) {
+	let text = "";
+	for (let index = 0; index < set.length; index++) {
+		const { key, value } = set[index];
+		text += `${index === 0 ? " " : ", "}${compileColumnName(target, key)} = ${compileExpression(context, scope, value)}`;
+	}
+	return text;
+}
+/** Compiles the physical name of the column of the table of `target` under `key`, as `SET`, the column list of an insert, and the target of `ON CONFLICT` name it, without an alias. */
 function compileColumnName(target, key) {
 	return quoteIdentifier(requireColumn(target.table, key).attributes.name ?? key);
 }
@@ -1314,6 +1352,10 @@ function isRelationDeclaration(value) {
 	return typeof value === "object" && value !== null && declarationBrand in value;
 }
 // src/query/rows.ts
+/** Returns the rows mode of a query that starts from `table`, as `TableQueryState` gives it in types: `optional` of the one row of a singleton table, and `many` of the rows of another table. */
+function getTableRows(table) {
+	return table.singleton ? "optional" : "many";
+}
 /** Returns the rows mode of a query of the records of `relation`, as `RelationRows` gives it in types. */
 function getRelationRows(relation) {
 	if (relation.kind === "many") return "many";
@@ -1333,8 +1375,15 @@ function toValueRows(rows) {
 	return rows === "nullable" ? "optional" : rows;
 }
 // src/query/node.ts
-/** Creates a query of all rows of `from`, or of the records of `relation` with `filters` in the rows mode of the relation. */
+/** Empty values of the key without columns of a query that starts from a singleton table. */
+const singletonKey = /* @__PURE__ */ Object.freeze({});
+/**
+* Creates a query of all rows of `from`, or of the records of `relation` with `filters` in the rows mode of the relation.
+*
+* A query of a singleton table without `relation` is a query of its one row, as of `find` of a key without columns, which `upsert` applies to.
+*/
 function createQueryNode(from, relation, filters = noFilters) {
+	const singleton = relation === void 0 && from.table.singleton;
 	return Object.freeze({
 		kind: "query",
 		from,
@@ -1350,16 +1399,17 @@ function createQueryNode(from, relation, filters = noFilters) {
 		distinctOn: [],
 		distinctFields: void 0,
 		lock: void 0,
-		rows: relation === void 0 ? "many" : getRelationRows(relation),
+		rows: relation === void 0 ? getTableRows(from.table) : getRelationRows(relation),
 		value: false,
 		guaranteed: relation?.required ?? false,
 		all: false,
-		conversion: void 0
+		conversion: void 0,
+		foundKey: singleton ? singletonKey : void 0
 	});
 }
-/** Tells whether `node` is a query of a table without clauses, such as a table of a `Db`: no relation, filters, selected fields, keys of groups, order, limit, offset, `distinct`, keys of `distinctOn`, row lock, rows other than `many`, `all`, or conversion. */
+/** Tells whether `node` is a query of a table without clauses, such as a table of a `Db`: no relation, filters, selected fields, keys of groups, order, limit, offset, `distinct`, keys of `distinctOn`, row lock, rows other than those that the table starts with, `many` or `optional` of a singleton table, `all`, or conversion. */
 function isTableQuery(node) {
-	return node.relation === void 0 && node.projections.length === 0 && node.filters.relation === void 0 && node.filters.scope === void 0 && node.filters.user === void 0 && node.groupBy.length === 0 && node.orderBy.length === 0 && node.limit === void 0 && node.offset === void 0 && !node.distinct && node.distinctOn.length === 0 && node.lock === void 0 && node.rows === "many" && !node.all && node.conversion === void 0;
+	return node.relation === void 0 && node.projections.length === 0 && node.filters.relation === void 0 && node.filters.scope === void 0 && node.filters.user === void 0 && node.groupBy.length === 0 && node.orderBy.length === 0 && node.limit === void 0 && node.offset === void 0 && !node.distinct && node.distinctOn.length === 0 && node.lock === void 0 && node.rows === getTableRows(node.from.table) && !node.all && node.conversion === void 0;
 }
 /** Tells whether a selected field is the rows of a nested query. */
 function isNestedSelection(node) {
@@ -2260,12 +2310,14 @@ function lowerMutation(node, context) {
 	switch (node.kind) {
 		case "insert": {
 			const values = lowerEach(node.values, context, lowerRow);
-			if (lowered === returning && values === node.values) return node;
+			const conflict = lowerConflict(node.conflict, context);
+			if (lowered === returning && values === node.values && conflict === node.conflict) return node;
 			return Object.freeze({
 				kind: "insert",
 				target,
 				columns: node.columns,
 				values,
+				conflict,
 				returning: lowered,
 				recordTemplate,
 				conversion,
@@ -2310,6 +2362,19 @@ function lowerMutation(node, context) {
 function lowerRow(row, context) {
 	return lowerEach(row, context, lowerValue);
 }
+/** Lowers the values of `DO UPDATE` of `ON CONFLICT` of an insert, keeping a conflict without queries in them as it is. */
+function lowerConflict(conflict, context) {
+	if (conflict?.update === void 0) return conflict;
+	const { target, update } = conflict;
+	const set = lowerEach(update.set, context, lowerAssignment);
+	return set === update.set ? conflict : Object.freeze({
+		target,
+		update: Object.freeze({
+			set,
+			excluded: update.excluded
+		})
+	});
+}
 function lowerAssignment(assignment, context) {
 	const value = lowerExpression(assignment.value, context);
 	return value === assignment.value ? assignment : Object.freeze({
@@ -2594,7 +2659,8 @@ var TransformedQuery = class {
 function transformQuery(node, db, callback) {
 	return new TransformedQuery(Object.freeze({
 		...node,
-		conversion: addTransform(node.conversion, callback)
+		conversion: addTransform(node.conversion, callback),
+		foundKey: void 0
 	}), db);
 }
 /**
@@ -2739,6 +2805,19 @@ function toKeyValues(table, values) {
 	}
 	return filter;
 }
+/**
+* Returns the target of `onConflict` of `columns`: the key of `table` of exactly these columns, primary or unique, in the order of the key, or none for a conflict on any key when there are no columns.
+*
+* It rejects columns that are not exactly a key of `table`, as `isKey` tells.
+*/
+function toConflictTarget(table, columns) {
+	if (columns.length === 0) return noColumns;
+	const key = findKey(table, columns);
+	if (key === void 0) throw new Error(`onConflict takes the columns of one key of table "${table.name}", primary or unique, or none for any key, not columns ${quoteColumns(columns)}`);
+	return key;
+}
+/** Columns of the target of a conflict on any key. */
+const noColumns = /* @__PURE__ */ Object.freeze([]);
 /** Returns `value` of column `column` of a key of `table` that `method` takes, rejecting `null` and `undefined`. */
 function requireKeyValue(table, column, value, method) {
 	if (value === null || value === void 0) throw new TypeError(`${method} got ${value} for column "${column}" of table "${table.name}"; a value of a key is never null or undefined`);
@@ -3241,14 +3320,14 @@ function toInsertRows(table, records, method) {
 	};
 }
 /**
-* Returns the assignments of an update of the rows of `source` that `set` gives: the values of its columns, or a callback that receives the references of `source` with the relations of `context` and returns them, read when it is called.
+* Returns the assignments of an update of the rows of `source` that `set` gives: the values of its columns, or a callback that receives the references of `source` with the relations of `context`, and those of `excluded` for `DO UPDATE` of a conflict, and returns them, read when it is called.
 *
 * A value of `undefined` keeps its column, and an update must set at least one column.
 * It rejects a key that is not a column of the table of `source`, and a query other than of one value.
 */
-function toAssignments(source, set, context) {
+function toAssignments(source, set, context, excluded) {
 	const { table } = source;
-	const values = typeof set === "function" ? set(createSelectionRefs(source, context)) : set;
+	const values = typeof set !== "function" ? set : excluded === void 0 ? set(createSelectionRefs(source, context)) : set(createSelectionRefs(source, context), createSelectionRefs(excluded, noContext));
 	if (typeof values !== "object" || values === null) throw new TypeError(`update takes the values of the columns of table "${table.name}" or a callback that returns them`);
 	const assignments = [];
 	for (const key of Object.keys(values)) {
@@ -3319,6 +3398,12 @@ var MutationQuery = class MutationQuery {
 		if (this.node.returning === void 0 && result.node.returning?.length === 0) throw new Error("The callback of use must select at least one field, or not call select to return the number of the rows");
 		return result;
 	}
+	onConflict(...columns) {
+		const { node } = this;
+		if (node.kind !== "insert") throw new Error("onConflict applies only to insert and insertMany");
+		if (node.returning !== void 0 || node.conversion !== void 0 || node.conflict !== void 0) throw new Error("onConflict applies right after insert or insertMany, once; call select, get, pluck, map, and transform after its action");
+		return new ConflictTarget(this, toConflictTarget(this.table, columns));
+	}
 	toSQL(options) {
 		return compileToSQL(this, options);
 	}
@@ -3349,13 +3434,149 @@ var MutationQuery = class MutationQuery {
 	}
 };
 /**
+* Conflict target of an insert of state `S` on the key of columns `K`, or without columns for `never`, with methods that choose the action and return the mutation: without columns, `doNothing` takes any key, and `merge` and `update` the row of a singleton table.
+*
+* It is no query: awaiting it is a type error and rejects, so that an insert without an action does not resolve without running.
+*/
+var ConflictTarget = class {
+	insert;
+	target;
+	constructor(insert, target) {
+		this.insert = insert;
+		this.target = target;
+		Object.freeze(this);
+	}
+	doNothing() {
+		const rows = this.insert.node.rows;
+		return this.derive(Object.freeze({ target: this.target }), rows === "one" ? "optional" : rows);
+	}
+	merge(...columns) {
+		const { insert } = this;
+		const target = this.target;
+		const updateTarget = toUpdateTarget(insert.table, target, "merge");
+		const node = this.insertNode();
+		const merged = columns.length === 0 ? node.columns.filter((key) => !target.includes(key)) : columns;
+		if (merged.length === 0) throw new Error("merge has no column to set, since the insert gives no column apart from the key of onConflict; use doNothing");
+		const excluded = createExcluded(insert.table);
+		const set = [];
+		for (const key of merged) {
+			requireColumn(insert.table, key);
+			if (target.includes(key)) throw new Error(`merge cannot set "${key}", a column of the key of onConflict`);
+			if (set.some((assignment) => assignment.key === key)) throw new Error(`merge takes each column once, not "${key}" twice`);
+			const index = node.columns.indexOf(key);
+			if (index === -1 || node.values.some((row) => row[index] === void 0)) throw new Error(`merge cannot set "${key}", which a record does not give, so that its default would replace the value of the record; give it in every record or leave it out of merge`);
+			set.push(Object.freeze({
+				key,
+				value: createNode({
+					kind: "column",
+					source: excluded,
+					key
+				})
+			}));
+		}
+		return this.derive(Object.freeze({
+			target: updateTarget,
+			update: Object.freeze({
+				set,
+				excluded
+			})
+		}), node.rows);
+	}
+	update(set) {
+		const { insert } = this;
+		const target = toUpdateTarget(insert.table, this.target, "update");
+		const node = this.insertNode();
+		const excluded = createExcluded(insert.table);
+		const assignments = toAssignments(node.target, set, insert.context, excluded);
+		return this.derive(Object.freeze({
+			target,
+			update: Object.freeze({
+				set: assignments,
+				excluded
+			})
+		}), node.rows);
+	}
+	/** Rejects awaiting the conflict target, which needs an action, such as `doNothing()`. */
+	then(_action) {
+		throw new Error("onConflict needs an action before the mutation runs, such as doNothing()");
+	}
+	/** Returns the node of the insert, which `onConflict` takes only of an insert. */
+	insertNode() {
+		return this.insert.node;
+	}
+	/** Creates the insert of the same kind and `Db` with `conflict`, changing rows `rows`. */
+	derive(conflict, rows) {
+		const { insert } = this;
+		const node = this.insertNode();
+		return new MutationQuery(insert.table, Object.freeze({
+			kind: "insert",
+			target: node.target,
+			columns: node.columns,
+			values: node.values,
+			conflict,
+			returning: void 0,
+			rows,
+			value: false
+		}), insert.context, insert.db);
+	}
+};
+/**
+* Returns the target of `DO UPDATE` of `method` of a conflict on the columns `target` of a key of `table`: the columns, or without them the unique index of `(true)` of a singleton table.
+*
+* It rejects a target without columns of another table, since PostgreSQL requires an explicit conflict target for `DO UPDATE`.
+*/
+function toUpdateTarget(table, target, method) {
+	if (target.length > 0) return target;
+	if (table.singleton) return "singleton";
+	throw new Error(`${method} needs the columns of a key in onConflict, since PostgreSQL updates a record only on a conflict of a named key`);
+}
+/** Creates the occurrence of `table` that stands for the row proposed for insertion in `DO UPDATE`, `EXCLUDED` of PostgreSQL. */
+function createExcluded(table) {
+	return Object.freeze({
+		kind: "table",
+		table
+	});
+}
+/**
 * Creates the insert of `records` into the table of `query`, which must have no clauses, in rows mode `rows`: `one` for `insert` and `many` for `insertMany`, named by `method`.
 *
 * It returns the number of the inserted rows, until a selection returns their fields.
+* It rejects an insert of rows `many` into a singleton table, which holds one row.
 */
 function createInsert(query, records, rows, method) {
+	if (!isTableQuery(query.node)) throw new Error(`${method} applies only to a query of a table without clauses, such as filters or selected fields; select the fields that it returns after it`);
+	const { table } = query;
+	if (rows === "many" && table.singleton) throw new Error(`${method} cannot insert into singleton table "${table.name}", which holds one row; use insert or upsert`);
+	return createInsertInto(query, records, rows, method);
+}
+/**
+* Creates the upsert of `values` by `query`, a query of `find` or `findBy` of a table without other clauses, or of a singleton table without clauses.
+*
+* It inserts the values of the key of `query` with `values`, and on a conflict on that key, or on the row of a singleton table, sets the columns of `values` of the existing record, as `merge` of `onConflict` does.
+* It rejects another query, values that are not an object, a value of a column of the key, and values without a value other than `undefined`.
+*/
+function createUpsert(query, values) {
+	const { table } = query;
+	const { foundKey } = query.node;
+	if (foundKey === void 0) throw new Error("upsert applies only to a query of a singleton table or right after find or findBy of a query of a table, without clauses such as filters, optional, or selected fields; select the fields that it returns after it");
+	if (typeof values !== "object" || values === null) throw new TypeError(`upsert takes the values of the columns of table "${table.name}"`);
+	const key = Object.keys(foundKey);
+	const record = {};
+	for (const column of key) record[column] = foundKey[column];
+	let hasValues = false;
+	for (const column of Object.keys(values)) {
+		const value = values[column];
+		if (value === void 0) continue;
+		if (Object.hasOwn(foundKey, column)) throw new Error(`upsert takes the values of the columns other than the key of find or findBy, not of "${column}"`);
+		record[column] = value;
+		hasValues = true;
+	}
+	if (!hasValues) throw new Error(key.length === 0 ? "upsert takes the value of at least one column; to insert the row unless it exists, use insert(...).onConflict().doNothing()" : "upsert takes the value of at least one column other than the key; to insert the record of the key unless it exists, use insert(...).onConflict(...).doNothing()");
+	return new ConflictTarget(createInsertInto(query, [record], "one", "upsert"), key.length === 0 ? key : findKey(table, key)).merge();
+}
+/** Creates the insert of `records` into the occurrence of the table of `query`, whose clauses it does not read, in rows mode `rows` of the method named by `method`. */
+function createInsertInto(query, records, rows, method) {
 	const { node } = query;
-	if (!isTableQuery(node)) throw new Error(`${method} applies only to a query of a table without clauses, such as filters or selected fields; select the fields that it returns after it`);
 	const { columns, values } = toInsertRows(node.from.table, records, method);
 	return new MutationQuery(query.table, Object.freeze({
 		kind: "insert",
@@ -3395,7 +3616,7 @@ function createDelete(query) {
 	}), query.context, query.db);
 }
 /**
-* Rejects a query whose rows `method`, `update` or `delete`, cannot change: one of a relation, with selected fields, which a mutation selects after it, with a conversion of `map`, which a mutation takes after it too, with keys of groups, whose rows SQL does not give, with an order, a limit, an offset, `distinct`, or `distinctOn`, with a row lock, which a mutation takes on its rows itself, or without a filter that restricts its rows unless `all` allows it.
+* Rejects a query whose rows `method`, `update` or `delete`, cannot change: one of a relation, with selected fields, which a mutation selects after it, with a conversion of `map`, which a mutation takes after it too, with keys of groups, whose rows SQL does not give, with an order, a limit, an offset, `distinct`, or `distinctOn`, with a row lock, which a mutation takes on its rows itself, or without a filter that restricts its rows unless `all` allows it or the table is a singleton table.
 *
 * A filter simplified to `TRUE`, such as `where({})`, restricts no row.
 */
@@ -3406,8 +3627,9 @@ function checkChangedRows(node, method) {
 	if (node.groupBy.length > 0) throw new Error(`${method} changes rows rather than groups; choose them with where, find, or findBy instead of groupBy`);
 	if (node.orderBy.length > 0 || node.limit !== void 0 || node.offset !== void 0 || node.distinct || node.distinctOn.length > 0) throw new Error(`${method} cannot sort or limit the rows it changes; choose them with where, find, or findBy instead of take, limit, offset, orderBy, distinct, or distinctOn`);
 	if (node.lock !== void 0) throw new Error(`${method} locks the rows it changes itself, so its query takes no row lock`);
+	if (node.all || node.from.table.singleton) return;
 	const predicate = combineFilters(node.filters);
-	if (!node.all && predicate.kind === "boolean" && predicate.value) throw new Error(`${method} requires a filter that restricts the rows, such as of where or find; call all() to ${method} every row`);
+	if (predicate.kind === "boolean" && predicate.value) throw new Error(`${method} requires a filter that restricts the rows, such as of where or find; call all() to ${method} every row`);
 }
 // 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. */
@@ -3422,7 +3644,7 @@ 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 "";
+	if (node.relation === void 0 ? node.from.table.singleton : node.relation.kind === "one") return "";
 	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";
@@ -3593,6 +3815,9 @@ var SelectQuery = class SelectQuery {
 		if (!Array.isArray(records)) throw new TypeError("insertMany takes an array of records");
 		return createInsert(this, records, "many", "insertMany");
 	}
+	upsert(values) {
+		return createUpsert(this, values);
+	}
 	update(set) {
 		return createUpdate(this, set);
 	}
@@ -3645,10 +3870,11 @@ var SelectQuery = class SelectQuery {
 			db: this.db
 		});
 	}
-	/** Creates a query of the same kind and `Db` with the node changes applied. */
+	/** Creates a query of the same kind and `Db` with the node changes applied, dropping the key of `find` and `findBy` unless the changes give it. */
 	derive(changes) {
 		return new SelectQuery(this.table, Object.freeze({
 			...this.node,
+			foundKey: void 0,
 			...changes
 		}), this.context, this.db);
 	}
@@ -3699,10 +3925,15 @@ var SelectQuery = class SelectQuery {
 		const { node } = this;
 		return toFilteredRows(node.rows, node.value && node.conversion === void 0, node.guaranteed);
 	}
-	/** Creates the query of `find` and `findBy`: `where` of `values`, an object of column values, returning one row like `take`. */
+	/**
+	* Creates the query of `find` and `findBy`: `where` of `values`, an object of the values of the columns of a key, returning one row like `take`.
+	*
+	* On a query of a table without clauses, it keeps `values` as the key that `upsert` inserts.
+	*/
 	takeWhere(values) {
 		const changes = this.addFilter(values);
 		if (changes.rows === "many") changes.rows = "one";
+		if (isTableQuery(this.node)) changes.foundKey = Object.freeze(values);
 		return this.derive(changes);
 	}
 	/** Creates the query of one row with rows mode `rows` that `method` returns, rejecting a query of many rows. */
@@ -3750,7 +3981,6 @@ function requireDerived(query, result, subject) {
 function bindQuery(query, db) {
 	return new SelectQuery(query.table, query.node, query.context, db);
 }
-/** Starts a query over a new occurrence of the table. */
 function from(table) {
 	return startQuery(table, noContext);
 }