@morlay/rdbkit 0.0.0-stage → 0.0.1-alpha.2

package/dist/index.mjs

@@ -0,0 +1,1422 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Pool, types } from "pg";
+import Cursor from "pg-cursor";
+import { DatabaseSync } from "node:sqlite";
+// \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+// src/defs.ts
+/** 声明一张表（形状原样保留，另挂一个取句柄的钩子）。 */
+function defineTable(def) {
+	if (!/^[a-z][a-z0-9_]*$/u.test(def.name)) throw new Error(`rdbkit: table name '${def.name}' must match [a-z][a-z0-9_]*`);
+	const names = Object.keys(def.columns);
+	if (names.length === 0) throw new Error(`rdbkit: table '${def.name}' declares no columns`);
+	for (const name of names) if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw new Error(`rdbkit: table '${def.name}' column '${name}' must match [a-z][a-z0-9_]*`);
+	return {
+		...def,
+		table: (database) => database.table(def)
+	};
+}
+/** 声明一组表。 */
+function defineCatalog(tables) {
+	for (const table of tables) defineTable(table);
+	return tables;
+}
+// src/dialect.ts
+const SQLITE_KEYWORDS = /^[a-z][a-z0-9_]*$/u;
+function assertIdentifier(kind, name) {
+	if (!SQLITE_KEYWORDS.test(name)) throw new Error(`rdbkit: invalid ${kind} '${name}'`);
+}
+function createDialect(name) {
+	return name === "sqlite" ? sqliteDialect() : postgresDialect();
+}
+function sqliteDialect() {
+	return {
+		name: "sqlite",
+		quote(identifier) {
+			assertIdentifier("identifier", identifier);
+			return `"${identifier}"`;
+		},
+		tableName(table) {
+			assertIdentifier("table", table);
+			return `"${table}"`;
+		},
+		columnType(column) {
+			if (column.type === "serial") return "INTEGER";
+			if (column.type === "boolean") return "INTEGER";
+			if (column.type === "bigint" || column.type === "integer") return "INTEGER";
+			return "TEXT";
+		},
+		async readShape(database, table) {
+			if ((await database.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?", [table])).length === 0) return void 0;
+			const columns = await database.query(`PRAGMA table_info("${table}")`);
+			const indexes = await database.query(`PRAGMA index_list("${table}")`);
+			return {
+				columns: new Set(columns.map((row) => row.name)),
+				indexes: new Set(indexes.map((row) => row.name))
+			};
+		}
+	};
+}
+function postgresDialect() {
+	return {
+		name: "postgres",
+		quote(identifier) {
+			assertIdentifier("identifier", identifier);
+			return `"${identifier}"`;
+		},
+		tableName(table, schema = "public") {
+			assertIdentifier("schema", schema);
+			assertIdentifier("table", table);
+			return `"${schema}"."${table}"`;
+		},
+		columnType(column) {
+			switch (column.type) {
+				case "serial": return "SERIAL";
+				case "boolean": return "BOOLEAN";
+				case "bigint": return "BIGINT";
+				case "integer": return "INTEGER";
+				default: return "TEXT";
+			}
+		},
+		async readShape(database, table, schema = "public") {
+			const columns = await database.query("SELECT column_name FROM information_schema.columns WHERE table_schema = ? AND table_name = ?", [schema, table]);
+			if (columns.length === 0) return void 0;
+			const indexes = await database.query("SELECT indexname FROM pg_indexes WHERE schemaname = ? AND tablename = ?", [schema, table]);
+			return {
+				columns: new Set(columns.map((row) => row.column_name)),
+				indexes: new Set(indexes.map((row) => row.indexname))
+			};
+		}
+	};
+}
+/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）。 */
+function columnSql$1(dialect, name, column) {
+	assertIdentifier("column", name);
+	const parts = [dialect.quote(name), dialect.columnType(column)];
+	if (column.type === "serial" && dialect.name === "sqlite") parts.push("PRIMARY KEY AUTOINCREMENT");
+	else if (column.primaryKey === true) parts.push("PRIMARY KEY");
+	if (column.notNull === true) parts.push("NOT NULL");
+	if (column.unique === true) parts.push("UNIQUE");
+	if (column.default !== void 0) parts.push(`DEFAULT ${literal(dialect, column.default, column.type)}`);
+	if (column.references !== void 0) {
+		const { table, column: referenced, onDelete } = column.references;
+		assertIdentifier("table", table);
+		assertIdentifier("column", referenced);
+		parts.push(`REFERENCES ${dialect.tableName(table)}(${dialect.quote(referenced)})` + (onDelete === void 0 ? "" : ` ON DELETE ${onDelete.toUpperCase()}`));
+	}
+	return parts.join(" ");
+}
+function literal(dialect, value, type) {
+	if (type === "boolean") {
+		if (typeof value === "number") return dialect.name === "postgres" ? value === 0 ? "FALSE" : "TRUE" : String(value);
+		return dialect.name === "postgres" ? value.toUpperCase() : /^(true|1)$/iu.test(value) ? "1" : "0";
+	}
+	if (typeof value === "number") return String(value);
+	return `'${value.replaceAll("'", "''")}'`;
+}
+/** 建表语句（IF NOT EXISTS；列与表级约束都由定义算出来）。 */
+function createTableSql(dialect, table, schema) {
+	const parts = Object.entries(table.columns).map(([name, column]) => columnSql$1(dialect, name, column));
+	const primaryKey = table.primaryKey === void 0 ? void 0 : table.primaryKey.map((name) => dialect.quote(name)).join(", ");
+	if (primaryKey !== void 0) parts.push(`PRIMARY KEY (${primaryKey})`);
+	for (const [name, check] of Object.entries(table.checks ?? {})) {
+		assertIdentifier("constraint", name);
+		parts.push(`CONSTRAINT ${dialect.quote(name)} CHECK (${check.expression})`);
+	}
+	for (const [name, unique] of Object.entries(table.uniques ?? {})) {
+		assertIdentifier("constraint", name);
+		parts.push(`CONSTRAINT ${dialect.quote(name)} UNIQUE (${unique.columns.map((column) => dialect.quote(column)).join(", ")})`);
+	}
+	return `CREATE TABLE IF NOT EXISTS ${dialect.tableName(table.name, schema)} (\n  ${parts.join(",\n  ")}\n)`;
+}
+/** 索引语句（`unique` 时是唯一索引）。 */
+function createIndexSql(dialect, table, name, columns, unique = false) {
+	assertIdentifier("index", name);
+	return `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ${dialect.quote(name)} ON ${dialect.tableName(table.name)} (${columns.map((column) => dialect.quote(column)).join(", ")})`;
+}
+/** 删列（只在显式允许破坏性变更时用）。 */
+function dropColumnSql(dialect, table, name) {
+	assertIdentifier("column", name);
+	return `ALTER TABLE ${dialect.tableName(table)} DROP COLUMN ${dialect.quote(name)}`;
+}
+/** 删索引（只在显式允许破坏性变更时用）。 */
+function dropIndexSql(dialect, name) {
+	assertIdentifier("index", name);
+	return `DROP INDEX IF EXISTS ${dialect.quote(name)}`;
+}
+/** 加列语句（启动迁移只做「缺列则补」，不改类型、不删列）。 */
+function addColumnSql(dialect, table, name, column) {
+	return `ALTER TABLE ${dialect.tableName(table)} ADD COLUMN ${columnSql$1(dialect, name, column)}`;
+}
+// src/fragment.ts
+/** 一段纯文本；`only` 限定只在某个方言里出现（SQLite 不支持的行锁等）。 */
+function text(value, options = {}) {
+	return () => value === "" ? [] : [{
+		text: value,
+		...options.only === void 0 ? {} : { only: options.only }
+	}];
+}
+/** 一个绑定参数。 */
+function param(value) {
+	return () => [{ param: value }];
+}
+/**
+* 把 `?` 占位符与参数列表编成片段（便捷构造；我们生成的 SQL 只含占位符，不含字面量 `?`）。
+*/
+function fragment(sql, params = []) {
+	return () => {
+		const chunks = sql.split("?");
+		const parts = [];
+		for (const [index, chunk] of chunks.entries()) {
+			if (chunk !== "") parts.push({ text: chunk });
+			if (index < params.length) parts.push({ param: params[index] });
+		}
+		return parts;
+	};
+}
+/** 按顺序拼接（`separator` 只在两个非空片段之间插入，片段内部的各步不拆开）。 */
+function concat(fragments, separator = " ") {
+	return () => {
+		function* generate() {
+			let first = true;
+			for (const entry of fragments) {
+				const item = typeof entry === "string" ? text(entry) : entry;
+				let opened = false;
+				for (const part of item()) {
+					if (!opened) {
+						if (!first && separator !== "") yield { text: separator };
+						first = false;
+						opened = true;
+					}
+					yield part;
+				}
+			}
+		}
+		return generate();
+	};
+}
+/**
+* 把整段限定在某个方言里：每个片段步都带上 `only`，渲染时别的方言整段丢弃
+*（连同它的绑定参数——方言相关表达式靠这一条做到「只留本方言的占位符」）。
+*/
+function only(dialect, source) {
+	return () => {
+		const parts = [];
+		for (const part of source()) parts.push({
+			...part,
+			only: part.only ?? dialect
+		});
+		return parts;
+	};
+}
+/** 渲染成某方言的 SQL：SQLite 保持 `?`，PostgreSQL 用 `$1..$n`。 */
+function render(fragment, dialect) {
+	const params = [];
+	let sql = "";
+	for (const part of fragment()) {
+		if (part.only !== void 0 && part.only !== dialect) continue;
+		if ("text" in part) {
+			sql += part.text;
+			continue;
+		}
+		params.push(part.param);
+		sql += dialect === "sqlite" ? "?" : `$${String(params.length)}`;
+	}
+	return {
+		text: sql,
+		params
+	};
+}
+// src/expr.ts
+var expr_exports = /* @__PURE__ */ __exportAll({
+	add: () => add,
+	always: () => always,
+	and: () => and,
+	between: () => between,
+	coalesce: () => coalesce,
+	column: () => column,
+	columnSql: () => columnSql,
+	countIf: () => countIf,
+	eq: () => eq,
+	excluded: () => excluded,
+	exists: () => exists,
+	expr: () => expr,
+	gt: () => gt,
+	gte: () => gte,
+	inList: () => inList,
+	inSubquery: () => inSubquery,
+	isDistinctFrom: () => isDistinctFrom,
+	isNotNull: () => isNotNull,
+	isNull: () => isNull,
+	jsonInt: () => jsonInt,
+	jsonText: () => jsonText,
+	like: () => like,
+	localDay: () => localDay,
+	lower: () => lower,
+	lt: () => lt,
+	lte: () => lte,
+	maxOf: () => maxOf,
+	ne: () => ne,
+	never: () => never,
+	not: () => not,
+	notInList: () => notInList,
+	notInSubquery: () => notInSubquery,
+	notNull: () => notNull,
+	operandSql: () => operandSql,
+	or: () => or,
+	raw: () => raw,
+	toInt: () => toInt,
+	value: () => value
+});
+function column(name, table) {
+	return {
+		kind: "column",
+		name,
+		...table === void 0 ? {} : { table }
+	};
+}
+function value(input) {
+	return {
+		kind: "value",
+		value: input
+	};
+}
+/** 列名引用成 SQL：`"表"."列"` 或 `"列"`。 */
+function columnSql(ref) {
+	const name = `"${ref.name}"`;
+	return ref.table === void 0 ? name : `"${ref.table}".${name}`;
+}
+/** 把操作数渲染成片段（投影 / 赋值里复用）。 */
+function operandSql(ref) {
+	return operand(ref);
+}
+/** 表达式操作数的便捷构造（如 `expr('"f_count" + 1')`）。 */
+function expr(sql, params = []) {
+	return {
+		kind: "expr",
+		sql,
+		params
+	};
+}
+function asOperand(input) {
+	if (typeof input === "object" && input !== null && "kind" in input) return input;
+	return value(input);
+}
+function operand(ref) {
+	if (ref.kind === "column") return text(columnSql(ref));
+	if (ref.kind === "value") return param(ref.value);
+	return ref.fragment ?? fragment(ref.sql, ref.params);
+}
+/** 两个方言各给一份片段，由 rdbkit 在渲染时挑本方言的那份。 */
+function dialectExpr(sqlite, postgres) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([only("sqlite", sqlite), only("postgres", postgres)], "")
+	};
+}
+/** 输入转成片段（列 / 值 / 表达式都认）。 */
+function fragmentOf(input) {
+	return operand(asOperand(input));
+}
+function binary(left, operator, right) {
+	if (right === null) return concat([operand(asOperand(left)), text(`${operator === "=" ? "IS" : "IS NOT"} NULL`)]);
+	return concat([
+		operand(asOperand(left)),
+		text(operator),
+		operand(asOperand(right))
+	]);
+}
+const eq = (left, right) => binary(left, "=", right);
+const ne = (left, right) => binary(left, "<>", right);
+const gt = (left, right) => binary(left, ">", right);
+const gte = (left, right) => binary(left, ">=", right);
+const lt = (left, right) => binary(left, "<", right);
+const lte = (left, right) => binary(left, "<=", right);
+const like = (left, right) => binary(left, "LIKE", right);
+/** `BETWEEN ? AND ?`。 */
+const between = (ref, low, high) => concat([
+	operand(asOperand(ref)),
+	text("BETWEEN"),
+	operand(asOperand(low)),
+	text("AND"),
+	operand(asOperand(high))
+]);
+/** `列 IN (子查询)`。 */
+function inSubquery(ref, subquery) {
+	return concat([
+		operand(asOperand(ref)),
+		text("IN ("),
+		subquery,
+		text(")")
+	]);
+}
+/** `列 NOT IN (子查询)`。 */
+function notInSubquery(ref, subquery) {
+	return concat([
+		operand(asOperand(ref)),
+		text("NOT IN ("),
+		subquery,
+		text(")")
+	]);
+}
+/** 恒真条件（占位用，避免业务侧写 `raw("1 = 1")`）。 */
+function always() {
+	return raw("1 = 1");
+}
+/** 恒假条件。 */
+function never() {
+	return raw("1 = 0");
+}
+/** 函数式表达式：`名字(<参数>)`（值走绑定，参数可以是列 / 值 / 别的表达式）。 */
+function call(name, inputs) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([
+			text(`${name}(`),
+			concat(inputs.map((input) => operand(asOperand(input))), ", "),
+			text(")")
+		], "")
+	};
+}
+/** `COALESCE(a, b, …)`：值走绑定参数，列/表达式原样渲染。 */
+function coalesce(...inputs) {
+	return call("COALESCE", inputs);
+}
+/** `lower(x)`（表达式位置用）。 */
+function lower(input) {
+	return call("lower", [input]);
+}
+/** `x IS NOT NULL` 的表达式形式（投影 / 分组位置用）。 */
+function notNull(input) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([operand(asOperand(input)), text("IS NOT NULL")])
+	};
+}
+/** `a IS DISTINCT FROM b`（NULL 也参与比较，不会退化成 `IS NULL`）。 */
+function isDistinctFrom(left, right) {
+	return concat([
+		operand(asOperand(left)),
+		text("IS DISTINCT FROM"),
+		operand(asOperand(right))
+	]);
+}
+/** `EXISTS (子查询)`。 */
+function exists(subquery) {
+	return concat([
+		text("EXISTS ("),
+		subquery,
+		text(")")
+	]);
+}
+/** `NOT (...)`。 */
+const not = (condition) => concat([
+	text("NOT ("),
+	condition,
+	text(")")
+]);
+/**
+* 显式逃生口：少数表达不了的片段（窗口函数、方言专属函数）才用它。
+* 占位符仍只由 `?` + 参数生成，避免把值拼进文本。
+*/
+function raw(sql, params = []) {
+	return fragment(sql, params);
+}
+/** `a + b`（列自增、upsert 累加）。 */
+function add(left, right) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([
+			fragmentOf(left),
+			text("+"),
+			fragmentOf(right)
+		])
+	};
+}
+/** upsert 冲突时的「新值」引用：`excluded."列"`（只用于 `upsertExpr` 的赋值）。 */
+function excluded(name) {
+	if (!/^[a-z][a-z0-9_]*$/u.test(name)) throw new Error(`rdbkit: invalid column '${name}'`);
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: text(`excluded."${name}"`)
+	};
+}
+/** 条件渲染成整数列的值（`CASE WHEN cond THEN 1 ELSE 0 END`，两方言同一份）。 */
+function toInt(condition) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([
+			text("CASE WHEN"),
+			condition,
+			text("THEN 1 ELSE 0 END")
+		])
+	};
+}
+/** 条件计数：`SUM(CASE WHEN cond THEN 1 ELSE 0 END)`（投影 / 分组位置用）。 */
+function countIf(condition) {
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([
+			text("SUM("),
+			operand(toInt(condition)),
+			text(")")
+		], "")
+	};
+}
+/** 只增不减：`max(a, b)` 的方言无关写法（NULL 视作 0，两方言同一份 CASE）。 */
+function maxOf(first, ...rest) {
+	let current = fragmentOf(first);
+	for (const next of rest) {
+		const coalesced = concat([
+			text("COALESCE("),
+			current,
+			text(", 0)")
+		], "");
+		current = concat([
+			text("CASE WHEN"),
+			coalesced,
+			text("<"),
+			fragmentOf(next),
+			text("THEN"),
+			fragmentOf(next),
+			text("ELSE"),
+			coalesced,
+			text("END")
+		]);
+	}
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: current
+	};
+}
+/** JSON 路径（`$.a.b`）→ 段列表；段只允许标识符字符（PG 侧要内联进 `#>>` 的数组字面量）。 */
+function jsonPathParts(path) {
+	if (!path.startsWith("$.") || path.length < 3) throw new Error(`rdbkit: JSON path must look like '$.a.b', got '${path}'`);
+	const parts = path.slice(2).split(".");
+	for (const part of parts) if (!/^[A-Za-z0-9_]+$/u.test(part)) throw new Error(`rdbkit: unsupported JSON path segment '${part}' in '${path}'`);
+	return parts;
+}
+/** JSON 文本提取：SQLite `json_extract(列, 路径)`、PostgreSQL `列::json #>> '{a,b}'`。 */
+function jsonText(input, path) {
+	const parts = jsonPathParts(path);
+	return dialectExpr(concat([
+		text("json_extract("),
+		fragmentOf(input),
+		text(", "),
+		param(path),
+		text(")")
+	], ""), concat([
+		fragmentOf(input),
+		text("::json #>> "),
+		text(`'{${parts.join(",")}}'`)
+	], ""));
+}
+/** JSON 整数提取：文本提取后再转整数（SQLite 的 `json_extract` 本身就按类型给值）。 */
+function jsonInt(input, path) {
+	const parts = jsonPathParts(path);
+	return dialectExpr(concat([
+		text("json_extract("),
+		fragmentOf(input),
+		text(", "),
+		param(path),
+		text(")")
+	], ""), concat([
+		text("("),
+		fragmentOf(input),
+		text("::json #>> "),
+		text(`'{${parts.join(",")}}'`),
+		text(")::integer")
+	], ""));
+}
+/**
+* 毫秒时间戳 → 本地日（`YYYY-MM-DD`）。
+*
+* 按**数据库所在机器的本地时区**算（SQLite `localtime` / PG 会话时区），两方言口径一致。
+*/
+function localDay(input) {
+	return dialectExpr(concat([
+		text("date("),
+		fragmentOf(input),
+		text(" / 1000, 'unixepoch', 'localtime')")
+	], ""), concat([
+		text("to_char(to_timestamp("),
+		fragmentOf(input),
+		text(" / 1000.0), 'YYYY-MM-DD')")
+	], ""));
+}
+const isNull = (ref) => concat([operand(ref), text("IS NULL")]);
+const isNotNull = (ref) => concat([operand(ref), text("IS NOT NULL")]);
+/** `IN (?, ?, …)`；空列表渲染成恒假（`1 = 0`），避免拼出 `IN ()`。 */
+function inList(left, values) {
+	if (values.length === 0) return fragment("1 = 0");
+	return concat([operand(asOperand(left)), fragment(`IN (${values.map(() => "?").join(", ")})`, values)]);
+}
+/** `NOT IN (...)`；空列表恒真。 */
+function notInList(left, values) {
+	if (values.length === 0) return fragment("1 = 1");
+	return concat([operand(asOperand(left)), fragment(`NOT IN (${values.map(() => "?").join(", ")})`, values)]);
+}
+function isEmpty(value) {
+	for (const part of value()) return false;
+	return true;
+}
+function combine(keyword, conditions) {
+	const parts = conditions.filter((condition) => !isEmpty(condition));
+	if (parts.length === 0) return fragment(keyword === "AND" ? "1 = 1" : "1 = 0");
+	if (parts.length === 1) return parts[0];
+	const flat = parts.flatMap((condition, index) => index === 0 ? [condition] : [text(` ${keyword} `), condition]);
+	return concat([
+		text("("),
+		...flat,
+		text(")")
+	], "");
+}
+const and = (...conditions) => combine("AND", conditions);
+const or = (...conditions) => combine("OR", conditions);
+// src/compound.ts
+/** 把一条 CTE 拼在 `WITH` 之后（调用方负责逗号）。 */
+function cteSql(cte) {
+	const columns = cte.columns === void 0 ? "" : ` (${cte.columns.map((name) => `"${name}"`).join(", ")})`;
+	return concat([
+		text(`"${cte.name}"${columns} AS (`),
+		cte.query,
+		text(")")
+	], " ");
+}
+/** 组装 `WITH [RECURSIVE] cte, … SELECT …`。 */
+function withCtes(ctes, query) {
+	if (ctes.length === 0) return query;
+	return concat([
+		text(ctes.some((cte) => cte.recursive === true) ? "WITH RECURSIVE" : "WITH"),
+		concat(ctes.map(cteSql), ", "),
+		query
+	], " ");
+}
+/** `UNION` / `UNION ALL`。 */
+function union(left, right, options = {}) {
+	return concat([
+		left,
+		text(options.all === true ? "UNION ALL" : "UNION"),
+		right
+	], " ");
+}
+/** `INTERSECT`。 */
+function intersect(left, right) {
+	return concat([
+		left,
+		text("INTERSECT"),
+		right
+	], " ");
+}
+/** `EXCEPT`。 */
+function except(left, right) {
+	return concat([
+		left,
+		text("EXCEPT"),
+		right
+	], " ");
+}
+/** 行锁：只有 PostgreSQL 认，SQLite 渲染时整段丢掉（分隔符也不能漏出来）。 */
+function forUpdate(options = {}) {
+	const parts = ["FOR UPDATE"];
+	if (options.of !== void 0 && options.of.length > 0) parts.push(`OF ${options.of.map((name) => `"${name}"`).join(", ")}`);
+	if (options.noWait === true) parts.push("NOWAIT");
+	if (options.skipLocked === true) parts.push("SKIP LOCKED");
+	return text(parts.join(" "), { only: "postgres" });
+}
+/** 表别名（join / CTE 里用）。 */
+function aliasedTable(table, alias) {
+	return `"${table.name}" AS "${alias}"`;
+}
+// src/table/select.ts
+/** 表达式的片段：方言相关的表达式自带片段，普通的按 `sql` + 绑定参数编。 */
+function exprFragment(expression) {
+	return expression.fragment ?? fragment(expression.sql, expression.params);
+}
+/** COUNT(*)，投影里写 `{ n: count() }`。 */
+function count() {
+	return {
+		kind: "expr",
+		sql: "COUNT(*)",
+		params: []
+	};
+}
+/**
+* SUM(列)；多表查询时传表名避免歧义。
+*
+* PostgreSQL 的 `SUM(bigint)` 返回 `numeric`（驱动给字符串），SQLite 返回整数——统一 cast 回 int8，
+* 声明的 `number | bigint` 才成立。列类型只有 integer / bigint，所以这个 cast 不丢小数。
+*/
+function sum(name, table) {
+	const target = table === void 0 ? `"${name}"` : `"${table}"."${name}"`;
+	return {
+		kind: "expr",
+		sql: "",
+		params: [],
+		fragment: concat([only("sqlite", text(`SUM(${target})`)), only("postgres", text(`SUM(${target})::bigint`))], "")
+	};
+}
+function selectQuery(database, table, projection) {
+	const state = {
+		joins: [],
+		ctes: [],
+		distinct: false,
+		order: [],
+		group: []
+	};
+	/**
+	* 结果行的值归一：`bigint` 列统一成 JS `bigint`。
+	* SQLite 的 INTEGER 由驱动给 number，PostgreSQL 的 int8 已经是 BigInt（见 `bigintTypes`）——
+	* 读出来的类型不能跟着驱动走，否则同一份表定义在两种方言下值类型不同。
+	*/
+	const normalize = (row) => {
+		for (const [alias, entry] of Object.entries(projection)) {
+			if (entry.kind !== "column") continue;
+			if ((entry.table === void 0 ? table : tableOf(entry.table))?.columns[entry.name]?.type !== "bigint") continue;
+			const value = row[alias];
+			if (value === null || value === void 0 || typeof value === "bigint") continue;
+			row[alias] = BigInt(value);
+		}
+		return row;
+	};
+	const tableOf = (name) => {
+		if (name === table.name) return table;
+		for (const join of state.joins) if ((join.alias ?? join.table.name) === name) return join.table;
+	};
+	const toFragment = () => {
+		const items = Object.entries(projection).map(([alias, entry]) => entry.kind === "column" ? text(`${entry.table === void 0 ? "" : `"${entry.table}".`}"${entry.name}" AS "${alias}"`) : concat([exprFragment(entry), text(`AS "${alias}"`)], " "));
+		const parts = [
+			state.distinct ? text("SELECT DISTINCT") : text("SELECT"),
+			concat(items, ", "),
+			text(`FROM "${table.name}"`)
+		];
+		for (const join of state.joins) {
+			const target = join.alias === void 0 ? `"${join.table.name}"` : `"${join.table.name}" AS "${join.alias}"`;
+			if (join.kind === "cross") {
+				parts.push(text(`CROSS JOIN ${target}`));
+				continue;
+			}
+			const keyword = join.kind === "inner" ? "JOIN" : `${join.kind.toUpperCase()} JOIN`;
+			parts.push(text(`${keyword} ${target} ON`), join.on ?? text("1 = 1"));
+		}
+		if (state.condition !== void 0) parts.push(text("WHERE"), state.condition);
+		if (state.group.length > 0) {
+			const groupParts = state.group.map((item) => typeof item === "string" ? text(`"${table.name}"."${item}"`) : item.kind === "column" ? text(columnSql(item)) : exprFragment(item));
+			parts.push(text("GROUP BY"), concat(groupParts, ", "));
+		}
+		if (state.having !== void 0) parts.push(text("HAVING"), state.having);
+		if (state.order.length > 0) {
+			const orderParts = state.order.map((order) => {
+				return concat([typeof order.column === "string" ? text(`"${table.name}"."${order.column}"`) : order.column.kind === "column" ? text(columnSql(order.column)) : exprFragment(order.column), text(order.direction.toUpperCase())], " ");
+			});
+			parts.push(text("ORDER BY"), concat(orderParts, ", "));
+		}
+		if (state.limit !== void 0) parts.push(fragment("LIMIT ?", [state.limit]));
+		if (state.offset !== void 0) parts.push(fragment("OFFSET ?", [state.offset]));
+		if (state.lock !== void 0) parts.push(state.lock);
+		return withCtes(state.ctes, concat(parts, " "));
+	};
+	const query = {
+		where(condition) {
+			state.condition = state.condition === void 0 ? condition : and(state.condition, condition);
+			return query;
+		},
+		join(joined, on, kind = "inner", alias) {
+			state.joins.push({
+				table: joined,
+				on,
+				kind,
+				alias
+			});
+			return query;
+		},
+		with(name, queryText, options = {}) {
+			state.ctes.push({
+				name,
+				query: queryText,
+				...options
+			});
+			return query;
+		},
+		forUpdate(options) {
+			state.lock = forUpdate(options);
+			return query;
+		},
+		groupBy(...columns) {
+			state.group.push(...columns);
+			return query;
+		},
+		having(condition) {
+			state.having = condition;
+			return query;
+		},
+		distinct() {
+			state.distinct = true;
+			return query;
+		},
+		orderBy(column, direction = "asc") {
+			state.order.push({
+				column,
+				direction
+			});
+			return query;
+		},
+		limit(count) {
+			state.limit = count;
+			return query;
+		},
+		offset(count) {
+			state.offset = count;
+			return query;
+		},
+		toFragment,
+		async *[Symbol.asyncIterator]() {
+			for await (const row of database.iterate(toFragment())) yield normalize(row);
+		}
+	};
+	return query;
+}
+// src/table/render.ts
+function returningClause(returning) {
+	return returning === void 0 || returning.length === 0 ? "" : text(`RETURNING ${returning.map((name) => `"${name}"`).join(", ")}`);
+}
+function insertOf(table, row, mode, conflict, update, returning) {
+	const columns = Object.keys(row).filter((name) => table.columns[name] !== void 0);
+	if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+	const base = fragment(`INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) VALUES (${columns.map(() => "?").join(", ")})`, columns.map((name) => row[name]));
+	if (mode === "insert") return concat([base, returningClause(returning)], " ");
+	const target = (conflict ?? []).map((name) => `"${name}"`).join(", ");
+	if (mode === "ignore") return concat([base, `ON CONFLICT (${target}) DO NOTHING`], " ");
+	return concat([
+		base,
+		`ON CONFLICT (${target}) ${(update ?? []).length === 0 ? "DO NOTHING" : `DO UPDATE SET ${(update ?? []).map((name) => `"${name}" = excluded."${name}"`).join(", ")}`}`,
+		returningClause(returning)
+	], " ");
+}
+function insertManyOf(table, rows, options = {}) {
+	if (rows.length === 0) return fragment("SELECT 1 WHERE 1 = 0");
+	const columns = Object.keys(rows[0]).filter((name) => table.columns[name] !== void 0);
+	if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+	for (const row of rows) for (const column of columns) if (row[column] === void 0) throw new Error(`rdbkit: insertMany into "${table.name}" is missing column '${column}'`);
+	const tuple = `(${columns.map(() => "?").join(", ")})`;
+	return concat([fragment(`INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) VALUES ${rows.map(() => tuple).join(", ")}`, rows.flatMap((row) => columns.map((name) => row[name]))), conflictClause(options)], " ");
+}
+function insertFromSelectOf(table, columns, source, options = {}) {
+	if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
+	return concat([
+		text(`INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")})`),
+		source,
+		conflictClause(options)
+	], " ");
+}
+/** `ON CONFLICT …` 子句（没有冲突列时为空）。 */
+function conflictClause(options) {
+	const conflict = options.conflict ?? [];
+	if (conflict.length === 0) return "";
+	return text(`ON CONFLICT (${conflict.map((name) => `"${name}"`).join(", ")}) ${(options.update ?? []).length === 0 ? "DO NOTHING" : `DO UPDATE SET ${(options.update ?? []).map((name) => `"${name}" = excluded."${name}"`).join(", ")}`}`);
+}
+function upsertExprOf(table, row, conflict, assignments) {
+	const base = insertOf(table, row, "insert");
+	const target = conflict.map((name) => `"${name}"`).join(", ");
+	const sets = Object.entries(assignments).map(([name, ref]) => concat([text(`"${name}" =`), operandSql(ref)], " "));
+	return concat([
+		base,
+		text(`ON CONFLICT (${target}) DO UPDATE SET`),
+		concat(sets, ", ")
+	], " ");
+}
+function updateOf(table, patch, condition, returning) {
+	const columns = Object.keys(patch).filter((name) => table.columns[name] !== void 0);
+	if (columns.length === 0) throw new Error(`rdbkit: update "${table.name}" has no columns`);
+	const sets = columns.map((name) => {
+		const value = patch[name];
+		const assigned = typeof value === "object" && value !== null && "kind" in value ? operandSql(value) : param(value);
+		return concat([text(`"${name}" =`), assigned], " ");
+	});
+	const head = concat([text(`UPDATE "${table.name}" SET`), concat(sets, ", ")], " ");
+	return concat([condition === void 0 ? head : concat([
+		head,
+		text("WHERE"),
+		condition
+	], " "), returningClause(returning)], " ");
+}
+function deleteOf(table, condition, returning) {
+	const head = text(`DELETE FROM "${table.name}"`);
+	return concat([condition === void 0 ? head : concat([
+		head,
+		text("WHERE"),
+		condition
+	], " "), returningClause(returning)], " ");
+}
+// src/table/handle.ts
+function createTableHandle(database, definition) {
+	const name = definition.name;
+	return new Proxy({
+		name,
+		definition,
+		column: (column) => ({
+			kind: "column",
+			table: name,
+			name: column
+		}),
+		select: (projection) => selectQuery(database, definition, projection ?? Object.fromEntries(Object.keys(definition.columns).map((name) => [name, {
+			kind: "column",
+			table: definition.name,
+			name
+		}]))),
+		async insert(row, returning) {
+			return await database.write(insertOf(definition, row, "insert", void 0, void 0, returning));
+		},
+		async insertIgnore(row, conflict) {
+			await database.run(insertOf(definition, row, "ignore", conflict));
+		},
+		async insertFromSelect(columns, source, options) {
+			await database.run(insertFromSelectOf(definition, columns, source, options));
+		},
+		async insertMany(rows, options) {
+			await database.run(insertManyOf(definition, rows, options));
+		},
+		async upsert(row, conflict, update) {
+			await database.run(insertOf(definition, row, "upsert", conflict, update));
+		},
+		async update(patch, condition, returning) {
+			return await database.write(updateOf(definition, patch, condition, returning));
+		},
+		async upsertExpr(row, conflict, assignments) {
+			await database.run(upsertExprOf(definition, row, conflict, assignments));
+		},
+		async delete(condition, returning) {
+			if (returning !== void 0 && returning.length > 0) return await database.write(deleteOf(definition, condition, returning));
+			await database.run(deleteOf(definition, condition));
+			return [];
+		}
+	}, { get(target, property, receiver) {
+		if (typeof property === "string" && definition.columns[property] !== void 0) return {
+			kind: "column",
+			table: name,
+			name: property
+		};
+		return Reflect.get(target, property, receiver);
+	} });
+}
+// src/catalog.ts
+/** 把表定义列表编成索引（重复表名 fail loud）。 */
+function indexCatalog(catalog) {
+	const tables = /* @__PURE__ */ new Map();
+	for (const table of catalog) {
+		if (tables.has(table.name)) throw new Error(`rdbkit: duplicate table '${table.name}' in catalog`);
+		tables.set(table.name, table);
+	}
+	return {
+		get: (name) => tables.get(name),
+		has: (name) => tables.has(name),
+		names: () => [...tables.keys()]
+	};
+}
+// src/error.ts
+/** 统一的数据库错误：`kind` 是方言无关的判定，原始错误在 `cause`。 */
+var DbError = class extends Error {
+	kind;
+	constructor(kind, message, options) {
+		super(message, options);
+		this.kind = kind;
+		this.name = "DbError";
+	}
+};
+/**
+* 把驱动错误翻译成 {@link DbErrorKind}：SQLite 用错误文本前缀，PostgreSQL 用 SQLSTATE。
+* @param error - 驱动抛出的错误。
+* @param dialect - 产生它的方言。
+* @returns 已分类的错误（原错误在 `cause`）。
+*/
+function classifyError(error, dialect) {
+	if (error instanceof DbError) return error;
+	const cause = error;
+	const code = typeof cause?.code === "string" ? cause.code : void 0;
+	const message = typeof cause?.message === "string" ? cause.message : String(error);
+	if (dialect === "postgres") switch (code) {
+		case "23505": return new DbError("unique", message, { cause: error });
+		case "23503": return new DbError("foreign-key", message, { cause: error });
+		case "23502": return new DbError("not-null", message, { cause: error });
+		case "23514": return new DbError("check", message, { cause: error });
+		case "57014":
+		case "55P03": return new DbError("timeout", message, { cause: error });
+		case "53300": return new DbError("connection", message, { cause: error });
+		default:
+			if (code !== void 0 && code.startsWith("08")) return new DbError("connection", message, { cause: error });
+			return new DbError("unknown", message, { cause: error });
+	}
+	if (/UNIQUE constraint failed/iu.test(message)) return new DbError("unique", message, { cause: error });
+	if (/FOREIGN KEY constraint failed/iu.test(message)) return new DbError("foreign-key", message, { cause: error });
+	if (/NOT NULL constraint failed/iu.test(message)) return new DbError("not-null", message, { cause: error });
+	if (/CHECK constraint failed/iu.test(message)) return new DbError("check", message, { cause: error });
+	if (/SQLITE_BUSY|database is locked|database table is locked/iu.test(message)) return new DbError("timeout", message, { cause: error });
+	return new DbError("unknown", message, { cause: error });
+}
+// src/database/capabilities.ts
+function assertPragmaName(name) {
+	if (name !== "user_version" && name !== "application_id" && name !== "journal_mode") throw new Error(`rdbkit: unsupported pragma '${String(name)}'`);
+}
+/** PRAGMA 不支持绑定参数，值只能内联：只放行整数与标识符形状的字符串。 */
+function assertPragmaValue(name, value) {
+	if (typeof value === "number") {
+		if (!Number.isSafeInteger(value)) throw new Error(`rdbkit: invalid pragma value '${String(value)}' for '${name}'`);
+		return String(value);
+	}
+	if (!/^[A-Za-z][A-Za-z0-9_]*$/u.test(value)) throw new Error(`rdbkit: invalid pragma value '${value}' for '${name}'`);
+	return value;
+}
+/** 现有的表与视图名（迁移探测旧表、拒绝别人的库都要它）。 */
+async function objectNames(database) {
+	const query = database.dialect.name === "sqlite" ? fragment("SELECT name FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%'") : fragment("SELECT table_name AS name FROM information_schema.tables WHERE table_schema = current_schema()");
+	return (await database.read(query)).map((row) => row.name);
+}
+/** 回收空间与统计（SQLite `VACUUM` / PostgreSQL `VACUUM ANALYZE`）；不得在事务内调用。 */
+async function vacuum(database) {
+	await database.run(fragment(database.dialect.name === "sqlite" ? "VACUUM" : "VACUUM ANALYZE"));
+}
+/** 读 SQLite 的 `PRAGMA`（其它方言直接报不支持）。 */
+async function sqlitePragma(database, name) {
+	assertPragmaName(name);
+	if (database.dialect.name !== "sqlite") throw new Error(`rdbkit: '${name}' is a SQLite PRAGMA; this database is postgres`);
+	const value = (await database.read(fragment(`PRAGMA ${name}`)))[0]?.[name];
+	return typeof value === "number" || typeof value === "string" ? value : void 0;
+}
+/** 写 SQLite 的 `PRAGMA`（值只允许安全字面量，见 `assertPragmaValue`）。 */
+async function setSqlitePragma(database, name, value) {
+	assertPragmaName(name);
+	if (database.dialect.name !== "sqlite") throw new Error(`rdbkit: '${name}' is a SQLite PRAGMA; this database is postgres`);
+	await database.run(fragment(`PRAGMA ${name} = ${assertPragmaValue(name, value)}`));
+}
+// src/database/queue.ts
+/**
+* 写通道串行：同一实例的事务与写语句排队执行（SQLite 是单连接，PG 的 serializable 并发会冲突）。
+* 「当前异步上下文是否已在事务里」由方言层用 `AsyncLocalStorage` 判断（`sqlite.ts` / `postgres.ts`），
+* 这里只提供队列本身。
+*/
+function createSerialQueue() {
+	let tail = Promise.resolve();
+	return (fn) => {
+		const next = tail.then(fn, fn);
+		tail = next.then(() => void 0, () => void 0);
+		return next;
+	};
+}
+/** 保存点名：只在同一个事务里唯一即可。 */
+let savepointCounter = 0;
+function savepointName() {
+	savepointCounter += 1;
+	return `rdbkit_sp_${savepointCounter}`;
+}
+// src/database/postgres.ts
+/**
+* PostgreSQL 的 `bigint`（int8）与 `numeric` 默认由驱动给字符串。
+*
+* 值是 64 位整数时**不能用 Number 兜**（超过 `2^53` 就悄悄丢精度，`uint64` 的 ID 会撞车），所以：
+* - `int8`（OID 20）→ JS `BigInt`（精确，对应 Go 的 int64 / uint64）；
+* - `numeric`（OID 1700）保持驱动默认的字符串（可能是定点小数，BigInt 也不对）。
+*
+* 业务侧要 number 时自己 `Number(x)`（毫秒时间戳与计数在安全整数内，转换是安全的）。
+*/
+function bigintTypes() {
+	const INT8 = 20;
+	return { getTypeParser(oid, format) {
+		if (oid === INT8) return (value) => value === null ? null : BigInt(value);
+		return types.getTypeParser(oid, format);
+	} };
+}
+/** PostgreSQL 连接池：返回池上的执行面（游标 + int8 → BigInt）。 */
+function openPostgres(config) {
+	const pool = new Pool({
+		connectionString: config.connectionString,
+		types: bigintTypes()
+	});
+	const enqueue = createSerialQueue();
+	const current = new AsyncLocalStorage();
+	const cursorRows = async function* (client, text, params) {
+		const cursor = client.query(new Cursor(text, params));
+		try {
+			for (;;) {
+				const rows = await cursor.read(200);
+				if (rows.length === 0) return;
+				for (const row of rows) yield row;
+			}
+		} finally {
+			await cursor.close().catch(() => void 0);
+		}
+	};
+	const pooledIterate = async function* (text, params) {
+		const client = await pool.connect();
+		try {
+			yield* cursorRows(client, text, params);
+		} finally {
+			client.release();
+		}
+	};
+	/** 一条连接上的执行面（顶层事务与嵌套事务共用）。 */
+	const scopeOf = (client) => ({
+		iterate: (text, params) => cursorRows(client, text, params),
+		async run(text, params) {
+			await client.query(text, params);
+		},
+		transaction(fn) {
+			const name = savepointName();
+			return (async () => {
+				await client.query(`SAVEPOINT ${name}`);
+				try {
+					const result = await current.run(client, () => fn(scopeOf(client)));
+					await client.query(`RELEASE SAVEPOINT ${name}`);
+					return result;
+				} catch (error) {
+					await client.query(`ROLLBACK TO SAVEPOINT ${name}`);
+					await client.query(`RELEASE SAVEPOINT ${name}`);
+					throw error;
+				}
+			})();
+		},
+		async close() {}
+	});
+	return {
+		iterate: pooledIterate,
+		run(text, params) {
+			const client = current.getStore();
+			if (client !== void 0) return client.query(text, params).then(() => void 0);
+			return enqueue(async () => {
+				await pool.query(text, params);
+			});
+		},
+		transaction(fn) {
+			const held = current.getStore();
+			if (held !== void 0) return scopeOf(held).transaction(fn);
+			return enqueue(async () => {
+				const client = await pool.connect();
+				try {
+					await client.query(config.isolationLevel === void 0 ? "BEGIN" : `BEGIN ISOLATION LEVEL ${config.isolationLevel.toUpperCase()}`);
+					const result = await current.run(client, () => fn(scopeOf(client)));
+					await client.query("COMMIT");
+					return result;
+				} catch (error) {
+					await client.query("ROLLBACK");
+					throw error;
+				} finally {
+					client.release();
+				}
+			});
+		},
+		async close() {
+			await enqueue(async () => void 0);
+			await pool.end();
+		}
+	};
+}
+// src/database/sqlite.ts
+/** SQLite 连接调优：打开即设 PRAGMA，返回这条连接上的执行面。 */
+function openSqlite(config) {
+	const client = new DatabaseSync(config.path);
+	client.exec("PRAGMA foreign_keys = ON");
+	client.exec(`PRAGMA busy_timeout = ${config.busyTimeout ?? 5e3}`);
+	if (config.cacheSizeKb !== void 0) client.exec(`PRAGMA cache_size = -${config.cacheSizeKb}`);
+	if (config.mmapSize !== void 0) client.exec(`PRAGMA mmap_size = ${config.mmapSize}`);
+	if (config.journalMode !== void 0 && config.applyJournalMode !== false) client.exec(`PRAGMA journal_mode = ${config.journalMode}`);
+	const enqueue = createSerialQueue();
+	const current = new AsyncLocalStorage();
+	const executor = {
+		async *iterate(text, params) {
+			for (const row of client.prepare(text).iterate(...params)) yield row;
+		},
+		run(text, params) {
+			const write = async () => {
+				client.prepare(text).run(...params);
+			};
+			return current.getStore() === true ? write() : enqueue(write);
+		},
+		transaction(fn) {
+			if (current.getStore() === true) return (async () => {
+				const name = savepointName();
+				client.exec(`SAVEPOINT ${name}`);
+				try {
+					const result = await current.run(true, () => fn(executor));
+					client.exec(`RELEASE SAVEPOINT ${name}`);
+					return result;
+				} catch (error) {
+					client.exec(`ROLLBACK TO SAVEPOINT ${name}`);
+					client.exec(`RELEASE SAVEPOINT ${name}`);
+					throw error;
+				}
+			})();
+			return enqueue(async () => {
+				client.exec("BEGIN IMMEDIATE");
+				try {
+					const result = await current.run(true, () => fn(executor));
+					client.exec("COMMIT");
+					return result;
+				} catch (error) {
+					client.exec("ROLLBACK");
+					throw error;
+				}
+			});
+		},
+		async close() {
+			await enqueue(async () => void 0);
+			client.close();
+		}
+	};
+	return executor;
+}
+// src/database/create.ts
+/** 打开时的 catalog：按表名建一次索引（之后 `table("名字")` 才解析得到）。 */
+function withCatalog(config) {
+	return indexCatalog(config.catalog ?? []);
+}
+/** 打开一个库；这是连接创建的唯一入口（实际 connect 在 `sqlite.ts` / `postgres.ts`，业务只拿 `Database`）。 */
+async function openDatabase(config) {
+	const catalog = withCatalog(config);
+	const executor = config.dialect === "sqlite" ? openSqlite(config) : openPostgres(config);
+	return createDatabase(createDialect(config.dialect), executor, catalog, config.onQuery);
+}
+async function* iterateWrapped(rows, dialect) {
+	try {
+		for await (const row of rows) yield row;
+	} catch (error) {
+		throw classifyError(error, dialect);
+	}
+}
+function createDatabase(dialect, executor, catalog, onQuery) {
+	const observe = async (query, run) => {
+		const { text, params } = render(query, dialect.name);
+		const started = performance.now();
+		try {
+			const result = await run(text, params);
+			onQuery?.({
+				dialect: dialect.name,
+				sql: text,
+				params,
+				durationMs: performance.now() - started
+			});
+			return result;
+		} catch (error) {
+			onQuery?.({
+				dialect: dialect.name,
+				sql: text,
+				params,
+				durationMs: performance.now() - started,
+				error
+			});
+			throw classifyError(error, dialect.name);
+		}
+	};
+	const database = {
+		dialect,
+		catalog,
+		table: (source) => {
+			const definition = typeof source === "string" ? catalog.get(source) : source;
+			if (definition === void 0) throw new Error(`rdbkit: no table '${typeof source === "string" ? source : source.name}' in catalog`);
+			return createTableHandle(database, definition);
+		},
+		iterate(query) {
+			const { text, params } = render(query, dialect.name);
+			return iterateWrapped(executor.iterate(text, params), dialect.name);
+		},
+		read(query) {
+			return observe(query, async () => {
+				const rows = [];
+				for await (const row of database.iterate(query)) rows.push(row);
+				return rows;
+			});
+		},
+		write(query) {
+			return database.read(query);
+		},
+		run(query) {
+			return observe(query, (text, params) => executor.run(text, params));
+		},
+		transaction(fn) {
+			return executor.transaction((scoped) => fn(createDatabase(dialect, scoped, catalog, onQuery)));
+		},
+		objectNames: () => objectNames(database),
+		vacuum: () => vacuum(database),
+		sqlitePragma: (name) => sqlitePragma(database, name),
+		setSqlitePragma: (name, value) => setSqlitePragma(database, name, value),
+		async close() {
+			await executor.close();
+		}
+	};
+	return database;
+}
+// src/database/wrap.ts
+/** 把「已有执行面」包成 rdbkit 的 `Database`（宿主自己管连接与事务时用）。 */
+function wrapDatabase(dialectName, ports) {
+	const database = createDatabase(createDialect(dialectName), {
+		iterate: (text, params) => ports.iterate(text, params),
+		run: (text, params) => ports.run(text, params),
+		transaction: () => {
+			throw new Error("rdbkit: a wrapped database does not own transactions; use the host transaction");
+		},
+		close: async () => {
+			await ports.close?.();
+		}
+	}, indexCatalog([]));
+	return ports.transaction === void 0 ? database : {
+		...database,
+		transaction: ports.transaction
+	};
+}
+/** 结构迁移读取现状用的最小查询面。 */
+function shapeReader(database) {
+	return { async query(sql, params = []) {
+		return await database.read(fragment(sql, params));
+	} };
+}
+// src/migrate.ts
+/**
+* 结构差异（纯函数）：缺表建表、缺列补列、缺索引补索引。
+*
+* 默认只做「增」（缺表建表、缺列补列、缺索引补索引），不改类型、不删索引；删多出来的列只由
+* `allowDestructive: true` 显式打开（旧库升级默认不丢数据）。
+* @param dialect - 目标方言。
+* @param catalog - 表定义（唯一事实来源）。
+* @param shapes - 现有结构（表名 → 列 / 索引；不存在则 undefined）。
+* @param options - schema 名。
+* @returns 需要执行的变更，按依赖顺序（表 → 列 → 索引）。
+*/
+function planSchema(dialect, catalog, shapes, options = {}) {
+	const changes = [];
+	for (const table of catalog) {
+		const shape = shapes.get(table.name);
+		if (shape === void 0) changes.push({
+			table: table.name,
+			kind: "create-table",
+			statement: createTableSql(dialect, table, options.schema)
+		});
+		else {
+			for (const [name, column] of Object.entries(table.columns)) {
+				if (shape.columns.has(name)) continue;
+				changes.push({
+					table: table.name,
+					kind: "add-column",
+					statement: addColumnSql(dialect, table.name, name, assertAddable(table.name, name, column))
+				});
+			}
+			if (options.allowDestructive === true) for (const name of shape.columns) {
+				if (table.columns[name] !== void 0) continue;
+				changes.push({
+					table: table.name,
+					kind: "drop-column",
+					statement: dropColumnSql(dialect, table.name, name)
+				});
+			}
+		}
+		for (const [name, index] of Object.entries(table.indexes ?? {})) {
+			if (shape?.indexes.has(name) === true) continue;
+			changes.push({
+				table: table.name,
+				kind: "create-index",
+				statement: createIndexSql(dialect, table, name, index.columns)
+			});
+		}
+		for (const [name, unique] of Object.entries(table.uniques ?? {})) {
+			if (shape?.indexes.has(name) === true) continue;
+			changes.push({
+				table: table.name,
+				kind: "create-index",
+				statement: createIndexSql(dialect, table, name, unique.columns, true)
+			});
+		}
+	}
+	return changes;
+}
+function assertAddable(table, name, column) {
+	if (column.notNull === true && column.default === void 0) throw new Error(`rdbkit: cannot add NOT NULL column '${table}.${name}' without a default to an existing table`);
+	return column;
+}
+/** 让库结构与表定义对齐，并返回实际执行的语句。 */
+async function ensureSchema(database, catalog, options = {}) {
+	const shapes = /* @__PURE__ */ new Map();
+	for (const table of catalog) shapes.set(table.name, await database.dialect.readShape(shapeReader(database), table.name, options.schema));
+	const changes = planSchema(database.dialect, catalog, shapes, options);
+	for (const change of changes) {
+		options.onStatement?.(change.statement);
+		await database.run(fragment(change.statement));
+	}
+	return changes.map((change) => change.statement);
+}
+// src/migration.ts
+/** 内置迁移账本：一条已执行的数据迁移一行（`f_id` 唯一）。 */
+const schemaMigrations = defineTable({
+	name: "t_schema_migrations",
+	columns: {
+		f_id: {
+			type: "text",
+			primaryKey: true,
+			notNull: true
+		},
+		f_applied_at: {
+			type: "bigint",
+			notNull: true
+		}
+	}
+});
+/** 迁移注册表：业务把自己的迁移登记进来，打开库时一起执行。 */
+var MigrationRegistry = class {
+	#migrations = /* @__PURE__ */ new Map();
+	register(migration) {
+		if (this.#migrations.has(migration.id)) throw new Error(`rdbkit: migration '${migration.id}' is registered twice`);
+		this.#migrations.set(migration.id, migration);
+		return this;
+	}
+	list() {
+		return [...this.#migrations.values()].sort((left, right) => left.id.localeCompare(right.id));
+	}
+};
+/**
+* 先按 catalog 对齐结构（建表 / 补列 / 补索引），再执行未应用的数据迁移。
+*
+* 账本是 rdbkit 内置的 `t_schema_migrations`：每条迁移在**同一个事务**里执行并记账，
+* 失败即回滚，重跑时只跑没记过的。返回本次实际执行了哪些 `id`。
+*/
+async function runMigrations(database, options) {
+	const migrations = options.migrations instanceof MigrationRegistry ? options.migrations.list() : [...options.migrations];
+	await ensureSchema(database, [...options.catalog ?? [], schemaMigrations]);
+	const ledger = database.table(schemaMigrations);
+	const applied = /* @__PURE__ */ new Set();
+	for await (const row of ledger.select({ id: ledger.f_id })) applied.add(row.id);
+	const executed = [];
+	for (const migration of migrations) {
+		if (applied.has(migration.id)) continue;
+		if (await database.transaction(async (tx) => {
+			if (await migration.up(tx) === false) return false;
+			await tx.table(schemaMigrations).insert({
+				f_id: migration.id,
+				f_applied_at: Date.now()
+			});
+			return true;
+		})) executed.push(migration.id);
+	}
+	return executed;
+}
+export { DbError, expr_exports as E, MigrationRegistry, add, addColumnSql, aliasedTable, and, between, classifyError, column, columnSql as columnRefSql, columnSql$1 as columnSql, concat, count, countIf, createDialect, createIndexSql, createTableHandle, createTableSql, cteSql, defineCatalog, defineTable, dropColumnSql, dropIndexSql, ensureSchema, eq, except, excluded, exists, expr, forUpdate, fragment, gt, gte, inList, inSubquery, indexCatalog, intersect, isNotNull, isNull, jsonInt, jsonText, like, localDay, lt, lte, maxOf, ne, not, notInList, notInSubquery, openDatabase, operandSql, or, planSchema, raw, render, runMigrations, schemaMigrations, shapeReader, sum, toInt, union, value, withCtes, wrapDatabase };