@morlay/rdbkit 0.0.1 → 0.0.3

package/README.md

@@ -84,10 +84,22 @@ await database.setSqlitePragma("user_version", 4); // 写库身份（值只允
 ```
 
 
+## PostgreSQL schema
+
+连接配置里的 `schema` 是**唯一事实来源**：结构探测、DDL、表句柄的读写、迁移账本与 `objectNames` 都从
+`Database.schema` 取，一律渲染成 `"<schema>"."<表>"`（SQLite 没有 schema 概念，照旧不带前缀）。省略即
+`public`，不依赖连接串的 `search_path`。schema 本身要由部署方先建好（`CREATE SCHEMA ...`），rdbkit 不替你建。
+
+```ts
+const database = await openDatabase({ dialect: "postgres", connectionString, schema: "dsh_test" });
+await ensureSchema(database, catalog); // CREATE TABLE "dsh_test"."t_sessions" ...
+await runMigrations(database, { catalog, migrations }); // 账本也在 dsh_test
+```
+
 ## 迁移
 
 结构（建表 / 补列 / 补索引）由 `ensureSchema` 从表定义算差异；**数据迁移**走注册表，账本是内置的
-`t_schema_migrations`：
+`t_schema_migrations`（与业务表同 schema，见上节）：
 
 ```ts
 const migrations = new MigrationRegistry().register({

package/dist/index.mjs

@@ -98,8 +98,8 @@ function postgresDialect() {
 		}
 	};
 }
-/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）。 */
-function columnSql$1(dialect, name, column) {
+/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）；外键引用跟着表名一起落在同一 schema。 */
+function columnSql$1(dialect, name, column, schema) {
 	assertIdentifier("column", name);
 	const parts = [dialect.quote(name), dialect.columnType(column)];
 	if (column.type === "serial" && dialect.name === "sqlite") parts.push("PRIMARY KEY AUTOINCREMENT");
@@ -111,7 +111,7 @@ function columnSql$1(dialect, name, column) {
 		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()}`));
+		parts.push(`REFERENCES ${dialect.tableName(table, schema)}(${dialect.quote(referenced)})` + (onDelete === void 0 ? "" : ` ON DELETE ${onDelete.toUpperCase()}`));
 	}
 	return parts.join(" ");
 }
@@ -125,7 +125,7 @@ function literal(dialect, value, type) {
 }
 /** 建表语句（IF NOT EXISTS；列与表级约束都由定义算出来）。 */
 function createTableSql(dialect, table, schema) {
-	const parts = Object.entries(table.columns).map(([name, column]) => columnSql$1(dialect, name, column));
+	const parts = Object.entries(table.columns).map(([name, column]) => columnSql$1(dialect, name, column, schema));
 	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 ?? {})) {
@@ -139,14 +139,14 @@ function createTableSql(dialect, table, schema) {
 	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) {
+function createIndexSql(dialect, table, name, columns, unique = false, schema) {
 	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(", ")})`;
+	return `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ${dialect.quote(name)} ON ${dialect.tableName(table.name, schema)} (${columns.map((column) => dialect.quote(column)).join(", ")})`;
 }
 /** 删列（只在显式允许破坏性变更时用）。 */
-function dropColumnSql(dialect, table, name) {
+function dropColumnSql(dialect, table, name, schema) {
 	assertIdentifier("column", name);
-	return `ALTER TABLE ${dialect.tableName(table)} DROP COLUMN ${dialect.quote(name)}`;
+	return `ALTER TABLE ${dialect.tableName(table, schema)} DROP COLUMN ${dialect.quote(name)}`;
 }
 /** 删索引（只在显式允许破坏性变更时用）。 */
 function dropIndexSql(dialect, name) {
@@ -154,8 +154,8 @@ function dropIndexSql(dialect, 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)}`;
+function addColumnSql(dialect, table, name, column, schema) {
+	return `ALTER TABLE ${dialect.tableName(table, schema)} ADD COLUMN ${columnSql$1(dialect, name, column, schema)}`;
 }
 // src/fragment.ts
 /** 一段纯文本；`only` 限定只在某个方言里出现（SQLite 不支持的行锁等）。 */
@@ -708,15 +708,16 @@ function selectQuery(database, table, projection) {
 		if (name === table.name) return table;
 		for (const join of state.joins) if ((join.alias ?? join.table.name) === name) return join.table;
 	};
+	const targetOf = (definition) => database.dialect.tableName(definition.name, database.schema);
 	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}"`)
+			text(`FROM ${targetOf(table)}`)
 		];
 		for (const join of state.joins) {
-			const target = join.alias === void 0 ? `"${join.table.name}"` : `"${join.table.name}" AS "${join.alias}"`;
+			const target = join.alias === void 0 ? targetOf(join.table) : `${targetOf(join.table)} AS "${join.alias}"`;
 			if (join.kind === "cross") {
 				parts.push(text(`CROSS JOIN ${target}`));
 				continue;
@@ -805,31 +806,31 @@ function selectQuery(database, table, projection) {
 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) {
+function insertOf(table, target, 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]));
+	const base = fragment(`INSERT INTO ${target} (${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`], " ");
+	const conflictTarget = (conflict ?? []).map((name) => `"${name}"`).join(", ");
+	if (mode === "ignore") return concat([base, `ON CONFLICT (${conflictTarget}) DO NOTHING`], " ");
 	return concat([
 		base,
-		`ON CONFLICT (${target}) ${(update ?? []).length === 0 ? "DO NOTHING" : `DO UPDATE SET ${(update ?? []).map((name) => `"${name}" = excluded."${name}"`).join(", ")}`}`,
+		`ON CONFLICT (${conflictTarget}) ${(update ?? []).length === 0 ? "DO NOTHING" : `DO UPDATE SET ${(update ?? []).map((name) => `"${name}" = excluded."${name}"`).join(", ")}`}`,
 		returningClause(returning)
 	], " ");
 }
-function insertManyOf(table, rows, options = {}) {
+function insertManyOf(table, target, 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)], " ");
+	return concat([fragment(`INSERT INTO ${target} (${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 = {}) {
+function insertFromSelectOf(table, target, 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(", ")})`),
+		text(`INSERT INTO ${target} (${columns.map((name) => `"${name}"`).join(", ")})`),
 		source,
 		conflictClause(options)
 	], " ");
@@ -840,17 +841,17 @@ function conflictClause(options) {
 	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(", ");
+function upsertExprOf(table, target, row, conflict, assignments) {
+	const base = insertOf(table, target, row, "insert");
+	const conflictTarget = 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`),
+		text(`ON CONFLICT (${conflictTarget}) DO UPDATE SET`),
 		concat(sets, ", ")
 	], " ");
 }
-function updateOf(table, patch, condition, returning) {
+function updateOf(table, target, 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) => {
@@ -858,15 +859,15 @@ function updateOf(table, patch, condition, returning) {
 		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, ", ")], " ");
+	const head = concat([text(`UPDATE ${target} 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}"`);
+function deleteOf(table, target, condition, returning) {
+	const head = text(`DELETE FROM ${target}`);
 	return concat([condition === void 0 ? head : concat([
 		head,
 		text("WHERE"),
@@ -876,6 +877,7 @@ function deleteOf(table, condition, returning) {
 // src/table/handle.ts
 function createTableHandle(database, definition) {
 	const name = definition.name;
+	const target = database.dialect.tableName(name, database.schema);
 	return new Proxy({
 		name,
 		definition,
@@ -890,29 +892,29 @@ function createTableHandle(database, definition) {
 			name
 		}]))),
 		async insert(row, returning) {
-			return await database.write(insertOf(definition, row, "insert", void 0, void 0, returning));
+			return await database.write(insertOf(definition, target, row, "insert", void 0, void 0, returning));
 		},
 		async insertIgnore(row, conflict) {
-			await database.run(insertOf(definition, row, "ignore", conflict));
+			await database.run(insertOf(definition, target, row, "ignore", conflict));
 		},
 		async insertFromSelect(columns, source, options) {
-			await database.run(insertFromSelectOf(definition, columns, source, options));
+			await database.run(insertFromSelectOf(definition, target, columns, source, options));
 		},
 		async insertMany(rows, options) {
-			await database.run(insertManyOf(definition, rows, options));
+			await database.run(insertManyOf(definition, target, rows, options));
 		},
 		async upsert(row, conflict, update) {
-			await database.run(insertOf(definition, row, "upsert", conflict, update));
+			await database.run(insertOf(definition, target, row, "upsert", conflict, update));
 		},
 		async update(patch, condition, returning) {
-			return await database.write(updateOf(definition, patch, condition, returning));
+			return await database.write(updateOf(definition, target, patch, condition, returning));
 		},
 		async upsertExpr(row, conflict, assignments) {
-			await database.run(upsertExprOf(definition, row, conflict, assignments));
+			await database.run(upsertExprOf(definition, target, 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));
+			if (returning !== void 0 && returning.length > 0) return await database.write(deleteOf(definition, target, condition, returning));
+			await database.run(deleteOf(definition, target, condition));
 			return [];
 		}
 	}, { get(target, property, receiver) {
@@ -993,7 +995,7 @@ function assertPragmaValue(name, 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()");
+	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 = COALESCE(?, current_schema())", [database.schema ?? null]);
 	return (await database.read(query)).map((row) => row.name);
 }
 /** 回收空间与统计（SQLite `VACUUM` / PostgreSQL `VACUUM ANALYZE`）；不得在事务内调用。 */
@@ -1197,7 +1199,10 @@ function withCatalog(config) {
 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);
+	return createDatabase(createDialect(config.dialect), executor, catalog, {
+		schema: config.dialect === "postgres" ? config.schema : void 0,
+		onQuery: config.onQuery
+	});
 }
 async function* iterateWrapped(rows, dialect) {
 	try {
@@ -1206,7 +1211,9 @@ async function* iterateWrapped(rows, dialect) {
 		throw classifyError(error, dialect);
 	}
 }
-function createDatabase(dialect, executor, catalog, onQuery) {
+function createDatabase(dialect, executor, catalog, options = {}) {
+	const { onQuery } = options;
+	const schema = dialect.name === "postgres" ? options.schema ?? "public" : void 0;
 	const observe = async (query, run) => {
 		const { text, params } = render(query, dialect.name);
 		const started = performance.now();
@@ -1233,6 +1240,7 @@ function createDatabase(dialect, executor, catalog, onQuery) {
 	const database = {
 		dialect,
 		catalog,
+		schema,
 		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`);
@@ -1256,7 +1264,10 @@ function createDatabase(dialect, executor, catalog, onQuery) {
 			return observe(query, (text, params) => executor.run(text, params));
 		},
 		transaction(fn) {
-			return executor.transaction((scoped) => fn(createDatabase(dialect, scoped, catalog, onQuery)));
+			return executor.transaction((scoped) => fn(createDatabase(dialect, scoped, catalog, {
+				schema,
+				onQuery
+			})));
 		},
 		objectNames: () => objectNames(database),
 		vacuum: () => vacuum(database),
@@ -1280,7 +1291,7 @@ function wrapDatabase(dialectName, ports) {
 		close: async () => {
 			await ports.close?.();
 		}
-	}, indexCatalog([]));
+	}, indexCatalog([]), { schema: ports.schema });
 	return ports.transaction === void 0 ? database : {
 		...database,
 		transaction: ports.transaction
@@ -1319,7 +1330,7 @@ function planSchema(dialect, catalog, shapes, options = {}) {
 				changes.push({
 					table: table.name,
 					kind: "add-column",
-					statement: addColumnSql(dialect, table.name, name, assertAddable(table.name, name, column))
+					statement: addColumnSql(dialect, table.name, name, assertAddable(table.name, name, column), options.schema)
 				});
 			}
 			if (options.allowDestructive === true) for (const name of shape.columns) {
@@ -1327,7 +1338,7 @@ function planSchema(dialect, catalog, shapes, options = {}) {
 				changes.push({
 					table: table.name,
 					kind: "drop-column",
-					statement: dropColumnSql(dialect, table.name, name)
+					statement: dropColumnSql(dialect, table.name, name, options.schema)
 				});
 			}
 		}
@@ -1336,7 +1347,7 @@ function planSchema(dialect, catalog, shapes, options = {}) {
 			changes.push({
 				table: table.name,
 				kind: "create-index",
-				statement: createIndexSql(dialect, table, name, index.columns)
+				statement: createIndexSql(dialect, table, name, index.columns, false, options.schema)
 			});
 		}
 		for (const [name, unique] of Object.entries(table.uniques ?? {})) {
@@ -1344,7 +1355,7 @@ function planSchema(dialect, catalog, shapes, options = {}) {
 			changes.push({
 				table: table.name,
 				kind: "create-index",
-				statement: createIndexSql(dialect, table, name, unique.columns, true)
+				statement: createIndexSql(dialect, table, name, unique.columns, true, options.schema)
 			});
 		}
 	}
@@ -1356,9 +1367,13 @@ function assertAddable(table, name, column) {
 }
 /** 让库结构与表定义对齐，并返回实际执行的语句。 */
 async function ensureSchema(database, catalog, options = {}) {
+	const schema = options.schema ?? database.schema;
 	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 table of catalog) shapes.set(table.name, await database.dialect.readShape(shapeReader(database), table.name, schema));
+	const changes = planSchema(database.dialect, catalog, shapes, {
+		...options,
+		...schema === void 0 ? {} : { schema }
+	});
 	for (const change of changes) {
 		options.onStatement?.(change.statement);
 		await database.run(fragment(change.statement));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/rdbkit",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Schema-first RDB kit for DeepSeek Harness plugins: one table definition drives the DDL, the typed table handles and the startup migration for SQLite and PostgreSQL alike; business code only ever sees an injected Database.",
   "keywords": [
     "dsh",
@@ -44,7 +44,7 @@
   },
   "engines": {
     "node": ">=24.11.0",
-    "dsh": ">= 0.2.2-alpha.3 < 0.2.3"
+    "dsh": ">= 0.2.2-rc.1 < 0.2.3"
   },
   "scripts": {
     "build": "pnpm exec tsdown"

package/src/__tests__/pg.spec.ts

@@ -1,8 +1,5 @@
 import { describe, expect, it } from "vitest";
-import {
-  createPostgresTestDatabase,
-  type PostgresTestDatabase,
-} from "../testing.ts";
+import { createPostgresTestDatabase, type PostgresTestDatabase } from "../testing.ts";
 import {
   count,
   defineCatalog,
@@ -10,7 +7,9 @@ import {
   ensureSchema,
   fragment,
   openDatabase,
+  runMigrations,
   sum,
+  type Database,
 } from "../index.ts";
 
 const items = defineTable({
@@ -62,10 +61,11 @@ describe.skipIf(!process.env.TEST_PG_URL)("PostgreSQL 上同一套构建", () =>
 
       const table = database.table("t_items");
       const partTable = database.table("t_parts");
-      const [created] = await table.insert(
-        { f_owner: "a", f_count: 1, f_at: 1_788_852_417_123 },
-        ["f_id", "f_owner", "f_at"],
-      );
+      const [created] = await table.insert({ f_owner: "a", f_count: 1, f_at: 1_788_852_417_123 }, [
+        "f_id",
+        "f_owner",
+        "f_at",
+      ]);
       expect(created).toMatchObject({ f_owner: "a" });
       // 64 位整数读回来是 BigInt：超过 2^53 的 uint64 / int64 不会丢精度。
       expect(created?.f_at).toBe(1_788_852_417_123n);
@@ -114,6 +114,82 @@ describe.skipIf(!process.env.TEST_PG_URL)("PostgreSQL 上同一套构建", () =>
       await testDatabase.drop();
     }
   });
+
+  it("自定义 schema：DDL / 读写 / 迁移账本 / 结构探测都在同一处，public 不留副本", async () => {
+    const testDatabase: PostgresTestDatabase = await createPostgresTestDatabase();
+    const catalog = defineCatalog([items, parts]);
+    const config = {
+      dialect: "postgres" as const,
+      connectionString: testDatabase.connectionString,
+      schema: "dsh_test",
+      catalog,
+    };
+    const migration = {
+      id: "20261109-pg-schema-probe",
+      up: async (tx: Database) => {
+        await tx.table("t_items").insert({ f_owner: "migrated" });
+      },
+    };
+
+    const database = await openDatabase(config);
+    try {
+      await database.run(fragment('CREATE SCHEMA IF NOT EXISTS "dsh_test"'));
+
+      // 结构：建表与索引都限定到配置的 schema，且重复对齐是幂等的。
+      const statements = await ensureSchema(database, [items, parts]);
+      expect(statements.length).toBeGreaterThan(0);
+      expect(statements.every((statement) => statement.includes('"dsh_test".'))).toBe(true);
+      expect(await ensureSchema(database, [items, parts])).toEqual([]);
+
+      // 读写：句柄不依赖连接串的 search_path，直接落在配置的 schema。
+      const table = database.table("t_items");
+      await table.insert({ f_owner: "a", f_count: 1 });
+      const owners = await collect(table.select({ owner: table.column("f_owner") }));
+      expect(owners).toEqual([{ owner: "a" }]);
+
+      // 迁移账本：建表、读、记账都在同一 schema，重跑只跑没记过的。
+      expect(await runMigrations(database, { catalog, migrations: [migration] })).toEqual([
+        migration.id,
+      ]);
+      expect(await runMigrations(database, { catalog, migrations: [migration] })).toEqual([]);
+      const ledger = await database.read<{ f_id: string }>(
+        fragment('SELECT f_id FROM "dsh_test"."t_schema_migrations"'),
+      );
+      expect(ledger.map((row) => row.f_id)).toEqual([migration.id]);
+
+      // 结构探测跟着配置的 schema（旧数据迁移靠它判旧表在不在）。
+      expect(await database.objectNames()).toEqual(
+        expect.arrayContaining(["t_items", "t_schema_migrations"]),
+      );
+
+      // 表与账本都在 dsh_test，public 不留副本。
+      const placements = await database.read<{ table_schema: string; table_name: string }>(
+        fragment(
+          "SELECT table_schema, table_name FROM information_schema.tables " +
+            "WHERE table_name IN ('t_items', 't_parts', 't_schema_migrations') ORDER BY table_name",
+        ),
+      );
+      expect(placements.map((row) => `${row.table_schema}.${row.table_name}`)).toEqual([
+        "dsh_test.t_items",
+        "dsh_test.t_parts",
+        "dsh_test.t_schema_migrations",
+      ]);
+    } finally {
+      await database.close();
+    }
+
+    // 再次打开：结构已对齐、迁移已记账，数据还在。
+    const reopened = await openDatabase(config);
+    try {
+      expect(await ensureSchema(reopened, [items, parts])).toEqual([]);
+      expect(await runMigrations(reopened, { catalog, migrations: [migration] })).toEqual([]);
+      const [total] = await collect(reopened.table("t_items").select({ n: count() }));
+      expect(Number(total?.n)).toBe(2);
+    } finally {
+      await reopened.close();
+      await testDatabase.drop();
+    }
+  });
 });
 
 async function collect<T>(rows: AsyncIterable<T>): Promise<T[]> {

package/src/__tests__/schema.spec.ts

@@ -4,9 +4,15 @@ import {
   createTableSql,
   defineCatalog,
   defineTable,
+  E,
   ensureSchema,
   fragment,
   openDatabase,
+  planSchema,
+  render,
+  runMigrations,
+  wrapDatabase,
+  type Database,
 } from "../index.ts";
 
 const catalog = defineCatalog([
@@ -142,3 +148,126 @@ describe("SQLite 连接调优选项", () => {
     }
   });
 });
+/** 记录 SQL 的假 PostgreSQL 执行面：不需要真服务就能看表句柄 / 迁移渲染出来的语句。 */
+function recordingPostgres(schema?: string): {
+  database: Database;
+  statements: { text: string; params: readonly unknown[] }[];
+  reply: (rows: unknown[]) => void;
+} {
+  const statements: { text: string; params: readonly unknown[] }[] = [];
+  let rows: unknown[] = [];
+  let database: Database;
+  database = wrapDatabase("postgres", {
+    ...(schema === undefined ? {} : { schema }),
+    async *iterate(text, params) {
+      statements.push({ text, params });
+      yield* rows;
+    },
+    async run(text, params) {
+      statements.push({ text, params });
+    },
+    transaction: (fn) => fn(database),
+  });
+  return {
+    database,
+    statements,
+    reply(next) {
+      rows = next;
+    },
+  };
+}
+
+describe("PostgreSQL 自定义 schema", () => {
+  const postgres = createDialect("postgres");
+  const items = catalog[0]!;
+  const links = catalog[1]!;
+
+  it("DDL 的建表 / 外键引用 / 补列 / 索引都带 schema", () => {
+    const createLinks = createTableSql(postgres, links, "dsh_test");
+    expect(createLinks).toContain('CREATE TABLE IF NOT EXISTS "dsh_test"."t_links"');
+    expect(createLinks).toContain('REFERENCES "dsh_test"."t_items"("f_owner")');
+
+    const existing = new Map([
+      [
+        "t_items",
+        { columns: new Set(["f_id", "f_owner", "f_active"]), indexes: new Set<string>() },
+      ],
+    ]);
+    const statements = planSchema(postgres, catalog, existing, { schema: "dsh_test" }).map(
+      (change) => change.statement,
+    );
+    expect(statements).toContain(
+      'ALTER TABLE "dsh_test"."t_items" ADD COLUMN "f_count" INTEGER NOT NULL DEFAULT 0',
+    );
+    expect(statements).toContain(
+      'CREATE INDEX IF NOT EXISTS "idx_items_owner" ON "dsh_test"."t_items" ("f_owner")',
+    );
+    expect(statements.every((statement) => statement.includes('"dsh_test".'))).toBe(true);
+  });
+
+  it("表句柄的读写与 join 都指向配置的 schema", async () => {
+    const { database, statements } = recordingPostgres("dsh_test");
+    const table = database.table(items);
+    await table.insert({ f_owner: "a", f_count: 1, f_active: true });
+    await table.update({ f_count: 2 }, E.eq(table.f_owner, "a"));
+    await table.delete(E.eq(table.f_owner, "a"));
+
+    const sql = statements.map((statement) => statement.text);
+    expect(sql[0]).toContain('INSERT INTO "dsh_test"."t_items"');
+    expect(sql[1]).toContain('UPDATE "dsh_test"."t_items"');
+    expect(sql[2]).toContain('DELETE FROM "dsh_test"."t_items"');
+    expect(render(table.select().toFragment(), "postgres").text).toContain(
+      'FROM "dsh_test"."t_items"',
+    );
+    const linksTable = database.table(links);
+    expect(
+      render(
+        table
+          .select({ owner: table.f_owner })
+          .join(links, E.eq(table.f_owner, linksTable.f_owner))
+          .toFragment(),
+        "postgres",
+      ).text,
+    ).toContain('JOIN "dsh_test"."t_links"');
+  });
+
+  it("ensureSchema 与结构探测缺省用连接上的 schema", async () => {
+    const { database, statements } = recordingPostgres("dsh_test");
+    const applied = await ensureSchema(database, [items]);
+    expect(
+      applied.some((statement) =>
+        statement.includes('CREATE TABLE IF NOT EXISTS "dsh_test"."t_items"'),
+      ),
+    ).toBe(true);
+    expect(applied.every((statement) => statement.includes('"dsh_test".'))).toBe(true);
+    // 结构探测查的是配置的 schema，不是硬编码的 public。
+    expect(statements[0]!.text).toContain("information_schema.columns");
+    expect(statements[0]!.params).toEqual(["dsh_test", "t_items"]);
+  });
+
+  it("迁移账本的建表 / 读 / 记账都在配置的 schema", async () => {
+    const { database, statements } = recordingPostgres("dsh_test");
+    const migrations = [{ id: "20261109-probe", up: async () => {} }];
+    expect(await runMigrations(database, { catalog: [items], migrations })).toEqual([
+      "20261109-probe",
+    ]);
+    const sql = statements.map((statement) => statement.text);
+    expect(
+      sql.some((text) =>
+        text.includes('CREATE TABLE IF NOT EXISTS "dsh_test"."t_schema_migrations"'),
+      ),
+    ).toBe(true);
+    expect(sql.some((text) => text.includes('FROM "dsh_test"."t_schema_migrations"'))).toBe(true);
+    expect(sql.some((text) => text.includes('INSERT INTO "dsh_test"."t_schema_migrations"'))).toBe(
+      true,
+    );
+  });
+
+  it("objectNames 查配置的 schema", async () => {
+    const { database, statements } = recordingPostgres("dsh_test");
+    await database.objectNames();
+    expect(statements).toHaveLength(1);
+    expect(statements[0]!.text).toContain("information_schema.tables");
+    expect(statements[0]!.params).toEqual(["dsh_test"]);
+  });
+});

package/src/database/capabilities.ts

@@ -29,7 +29,8 @@ export async function objectNames(database: Database): Promise<string[]> {
           "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()",
+          "SELECT table_name AS name FROM information_schema.tables WHERE table_schema = COALESCE(?, current_schema())",
+          [database.schema ?? null],
         );
   const rows = await database.read<{ name: string }>(query);
   return rows.map((row) => row.name);

package/src/database/create.ts

@@ -21,12 +21,10 @@ export async function openDatabase<const C extends Catalog = Catalog>(
   const catalog = withCatalog(config);
   const executor =
     config.dialect === "sqlite" ? openSqlite(config) : openPostgres(config);
-  return createDatabase(
-    createDialect(config.dialect),
-    executor,
-    catalog,
-    config.onQuery,
-  ) as Database<C>;
+  return createDatabase(createDialect(config.dialect), executor, catalog, {
+    schema: config.dialect === "postgres" ? config.schema : undefined,
+    onQuery: config.onQuery,
+  }) as Database<C>;
 }
 
 async function* iterateWrapped<T>(
@@ -44,8 +42,14 @@ export function createDatabase(
   dialect: Dialect,
   executor: Executor,
   catalog: CatalogIndex,
-  onQuery?: (event: QueryEvent) => void,
+  options: {
+    schema?: string | undefined;
+    onQuery?: ((event: QueryEvent) => void) | undefined;
+  } = {},
 ): Database {
+  const { onQuery } = options;
+  // PostgreSQL 的目标 schema 只在这里定一次（缺省 public）；SQLite 没有 schema 概念。
+  const schema = dialect.name === "postgres" ? (options.schema ?? "public") : undefined;
   const observe = async <T>(
     query: Fragment,
     run: (text: string, params: readonly unknown[]) => Promise<T>,
@@ -75,6 +79,7 @@ export function createDatabase(
   const database: Database = {
     dialect,
     catalog,
+    schema,
     table: (source: TableDef | string) => {
       const definition = typeof source === "string" ? catalog.get(source) : source;
       if (definition === undefined) {
@@ -104,7 +109,7 @@ export function createDatabase(
     transaction(fn) {
       // catalog 跟着事务走：事务里按表名取句柄与外面一致。
       return executor.transaction((scoped) =>
-        fn(createDatabase(dialect, scoped, catalog, onQuery)),
+        fn(createDatabase(dialect, scoped, catalog, { schema, onQuery })),
       );
     },
     objectNames: () => objectNames(database),

package/src/database/types.ts

@@ -14,6 +14,11 @@ export interface Database<C extends Catalog = Catalog> {
   readonly dialect: Dialect;
   /** 装配层注册的 catalog（按表名解析；没注册时只能传定义）。 */
   readonly catalog: CatalogIndex;
+  /**
+   * 生成 SQL 的目标 schema：PostgreSQL 恒有值（配置缺省 `public`），SQLite 是 `undefined`。
+   * DDL、DML、迁移账本与结构探测都从这里取，不各自猜。
+   */
+  readonly schema: string | undefined;
   /** 按表名取（catalog 里有定义时保留强类型）。 */
   table<K extends C[number]["name"] & string>(
     name: K,

package/src/database/wrap.ts

@@ -8,6 +8,8 @@ import type { Database } from "./types.ts";
 export function wrapDatabase(
   dialectName: DialectName,
   ports: {
+    /** 宿主连接的目标 schema（PostgreSQL；省略即 `public`，与 rdbkit 默认一致）。 */
+    schema?: string | undefined;
     iterate(text: string, params: readonly unknown[]): AsyncIterable<unknown>;
     run(text: string, params: readonly unknown[]): Promise<void>;
     /** 宿主自己管事务时提供：把当前事务的执行面做成 scoped `Database`（对应 Go 的 `Tx(ctx, fn)`）。 */
@@ -30,6 +32,7 @@ export function wrapDatabase(
       },
     },
     indexCatalog([]),
+    { schema: ports.schema },
   );
   return ports.transaction === undefined
     ? database

package/src/dialect.ts

@@ -115,8 +115,13 @@ function postgresDialect(): Dialect {
   };
 }
 
-/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）。 */
-export function columnSql(dialect: Dialect, name: string, column: ColumnDef): string {
+/** 一列的定义 SQL（`"name" TEXT NOT NULL ...`）；外键引用跟着表名一起落在同一 schema。 */
+export function columnSql(
+  dialect: Dialect,
+  name: string,
+  column: ColumnDef,
+  schema?: string,
+): string {
   assertIdentifier("column", name);
   const parts = [dialect.quote(name), dialect.columnType(column)];
   if (column.type === "serial" && dialect.name === "sqlite")
@@ -131,7 +136,7 @@ export function columnSql(dialect: Dialect, name: string, column: ColumnDef): st
     assertIdentifier("table", table);
     assertIdentifier("column", referenced);
     parts.push(
-      `REFERENCES ${dialect.tableName(table)}(${dialect.quote(referenced)})` +
+      `REFERENCES ${dialect.tableName(table, schema)}(${dialect.quote(referenced)})` +
         (onDelete === undefined ? "" : ` ON DELETE ${onDelete.toUpperCase()}`),
     );
   }
@@ -156,7 +161,7 @@ function literal(dialect: Dialect, value: string | number, type: ColumnDef["type
 /** 建表语句（IF NOT EXISTS；列与表级约束都由定义算出来）。 */
 export function createTableSql(dialect: Dialect, table: TableDef, schema?: string): string {
   const parts = Object.entries(table.columns).map(([name, column]) =>
-    columnSql(dialect, name, column),
+    columnSql(dialect, name, column, schema),
   );
   const primaryKey =
     table.primaryKey === undefined
@@ -188,18 +193,24 @@ export function createIndexSql(
   name: string,
   columns: readonly string[],
   unique = false,
+  schema?: string,
 ): string {
   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(", ")})`
+    `ON ${dialect.tableName(table.name, schema)} (${columns.map((column) => dialect.quote(column)).join(", ")})`
   );
 }
 
 /** 删列（只在显式允许破坏性变更时用）。 */
-export function dropColumnSql(dialect: Dialect, table: string, name: string): string {
+export function dropColumnSql(
+  dialect: Dialect,
+  table: string,
+  name: string,
+  schema?: string,
+): string {
   assertIdentifier("column", name);
-  return `ALTER TABLE ${dialect.tableName(table)} DROP COLUMN ${dialect.quote(name)}`;
+  return `ALTER TABLE ${dialect.tableName(table, schema)} DROP COLUMN ${dialect.quote(name)}`;
 }
 
 /** 删索引（只在显式允许破坏性变更时用）。 */
@@ -214,6 +225,7 @@ export function addColumnSql(
   table: string,
   name: string,
   column: ColumnDef,
+  schema?: string,
 ): string {
-  return `ALTER TABLE ${dialect.tableName(table)} ADD COLUMN ${columnSql(dialect, name, column)}`;
+  return `ALTER TABLE ${dialect.tableName(table, schema)} ADD COLUMN ${columnSql(dialect, name, column, schema)}`;
 }

package/src/migrate.ts

@@ -19,7 +19,7 @@ export interface SchemaChange {
 }
 
 export interface EnsureSchemaOptions {
-  /** PostgreSQL 的 schema（默认 `public`）；SQLite 忽略。 */
+  /** PostgreSQL 的 schema（省略即 `database.schema`，再缺省是 `public`）；SQLite 忽略。 */
   schema?: string;
   /** 允许删掉定义里已经不存在、且确实多出来的列（默认关闭：升级不丢数据）。 */
   allowDestructive?: boolean;
@@ -64,6 +64,7 @@ export function planSchema(
             table.name,
             name,
             assertAddable(table.name, name, column),
+            options.schema,
           ),
         });
       }
@@ -73,7 +74,7 @@ export function planSchema(
           changes.push({
             table: table.name,
             kind: "drop-column",
-            statement: dropColumnSql(dialect, table.name, name),
+            statement: dropColumnSql(dialect, table.name, name, options.schema),
           });
         }
       }
@@ -83,7 +84,7 @@ export function planSchema(
       changes.push({
         table: table.name,
         kind: "create-index",
-        statement: createIndexSql(dialect, table, name, index.columns),
+        statement: createIndexSql(dialect, table, name, index.columns, false, options.schema),
       });
     }
     for (const [name, unique] of Object.entries(table.uniques ?? {})) {
@@ -92,7 +93,7 @@ export function planSchema(
       changes.push({
         table: table.name,
         kind: "create-index",
-        statement: createIndexSql(dialect, table, name, unique.columns, true),
+        statement: createIndexSql(dialect, table, name, unique.columns, true, options.schema),
       });
     }
   }
@@ -115,14 +116,19 @@ export async function ensureSchema(
   catalog: Catalog,
   options: EnsureSchemaOptions = {},
 ): Promise<string[]> {
+  // schema 是连接上的事实：配置给了就用配置的，没给就跟着连接打开时的有效 schema。
+  const schema = options.schema ?? database.schema;
   const shapes = new Map<string, TableShape | undefined>();
   for (const table of catalog) {
     shapes.set(
       table.name,
-      await database.dialect.readShape(shapeReader(database), table.name, options.schema),
+      await database.dialect.readShape(shapeReader(database), table.name, schema),
     );
   }
-  const changes = planSchema(database.dialect, catalog, shapes, options);
+  const changes = planSchema(database.dialect, catalog, shapes, {
+    ...options,
+    ...(schema === undefined ? {} : { schema }),
+  });
   for (const change of changes) {
     options.onStatement?.(change.statement);
     await database.run(fragment(change.statement));

package/src/table/handle.ts

@@ -83,6 +83,8 @@ export function createTableHandle<T extends TableDef>(
   definition: T,
 ): TableHandle<T> {
   const name = definition.name;
+  // 目标表名按连接的方言算一次（PostgreSQL 带 schema，SQLite 就是表名）。
+  const target = database.dialect.tableName(name, database.schema);
   const handle: TableHandleBase<T> = {
     name,
     definition,
@@ -101,32 +103,34 @@ export function createTableHandle<T extends TableDef>(
       ) as never,
     async insert(row, returning) {
       return await database.write<RowOf<T>>(
-        insertOf(definition, row, "insert", undefined, undefined, returning),
+        insertOf(definition, target, row, "insert", undefined, undefined, returning),
       );
     },
     async insertIgnore(row, conflict) {
-      await database.run(insertOf(definition, row, "ignore", conflict));
+      await database.run(insertOf(definition, target, row, "ignore", conflict));
     },
     async insertFromSelect(columns, source, options) {
-      await database.run(insertFromSelectOf(definition, columns, source, options));
+      await database.run(insertFromSelectOf(definition, target, columns, source, options));
     },
     async insertMany(rows, options) {
-      await database.run(insertManyOf(definition, rows, options));
+      await database.run(insertManyOf(definition, target, rows, options));
     },
     async upsert(row, conflict, update) {
-      await database.run(insertOf(definition, row, "upsert", conflict, update));
+      await database.run(insertOf(definition, target, row, "upsert", conflict, update));
     },
     async update(patch, condition, returning) {
-      return await database.write<RowOf<T>>(updateOf(definition, patch, condition, returning));
+      return await database.write<RowOf<T>>(
+        updateOf(definition, target, patch, condition, returning),
+      );
     },
     async upsertExpr(row, conflict, assignments) {
-      await database.run(upsertExprOf(definition, row, conflict, assignments));
+      await database.run(upsertExprOf(definition, target, row, conflict, assignments));
     },
     async delete(condition, returning) {
       if (returning !== undefined && returning.length > 0) {
-        return await database.write<RowOf<T>>(deleteOf(definition, condition, returning));
+        return await database.write<RowOf<T>>(deleteOf(definition, target, condition, returning));
       }
-      await database.run(deleteOf(definition, condition));
+      await database.run(deleteOf(definition, target, condition));
       return [];
     },
   };

package/src/table/render.ts

@@ -10,6 +10,7 @@ export function returningClause(returning?: readonly string[]): Fragment | strin
 
 export function insertOf(
   table: TableDef,
+  target: string,
   row: Record<string, unknown>,
   mode: "insert" | "ignore" | "upsert",
   conflict?: readonly string[],
@@ -19,26 +20,30 @@ export function insertOf(
   const columns = Object.keys(row).filter((name) => table.columns[name] !== undefined);
   if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
   const sql =
-    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) ` +
+    `INSERT INTO ${target} (${columns.map((name) => `"${name}"`).join(", ")}) ` +
     `VALUES (${columns.map(() => "?").join(", ")})`;
   const base = fragment(
     sql,
     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`], " ");
+  const conflictTarget = (conflict ?? []).map((name) => `"${name}"`).join(", ");
+  if (mode === "ignore") return concat([base, `ON CONFLICT (${conflictTarget}) DO NOTHING`], " ");
   const updates =
     (update ?? []).length === 0
       ? "DO NOTHING"
       : `DO UPDATE SET ${(update ?? [])
           .map((name) => `"${name}" = excluded."${name}"`)
           .join(", ")}`;
-  return concat([base, `ON CONFLICT (${target}) ${updates}`, returningClause(returning)], " ");
+  return concat(
+    [base, `ON CONFLICT (${conflictTarget}) ${updates}`, returningClause(returning)],
+    " ",
+  );
 }
 
 export function insertManyOf(
   table: TableDef,
+  target: string,
   rows: readonly Record<string, unknown>[],
   options: { conflict?: readonly string[]; update?: readonly string[] } = {},
 ): Fragment {
@@ -54,7 +59,7 @@ export function insertManyOf(
   }
   const tuple = `(${columns.map(() => "?").join(", ")})`;
   const sql =
-    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")}) ` +
+    `INSERT INTO ${target} (${columns.map((name) => `"${name}"`).join(", ")}) ` +
     `VALUES ${rows.map(() => tuple).join(", ")}`;
   const insert = fragment(
     sql,
@@ -65,14 +70,13 @@ export function insertManyOf(
 
 export function insertFromSelectOf(
   table: TableDef,
+  target: string,
   columns: readonly string[],
   source: Fragment,
   options: { conflict?: readonly string[]; update?: readonly string[] } = {},
 ): Fragment {
   if (columns.length === 0) throw new Error(`rdbkit: insert into "${table.name}" has no columns`);
-  const head = text(
-    `INSERT INTO "${table.name}" (${columns.map((name) => `"${name}"`).join(", ")})`,
-  );
+  const head = text(`INSERT INTO ${target} (${columns.map((name) => `"${name}"`).join(", ")})`);
   return concat([head, source, conflictClause(options)], " ");
 }
 
@@ -95,20 +99,25 @@ export function conflictClause(options: {
 
 export function upsertExprOf(
   table: TableDef,
+  target: string,
   row: Record<string, unknown>,
   conflict: readonly string[],
   assignments: Record<string, Operand>,
 ): Fragment {
-  const base = insertOf(table, row, "insert");
-  const target = conflict.map((name) => `"${name}"`).join(", ");
+  const base = insertOf(table, target, row, "insert");
+  const conflictTarget = 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, ", ")], " ");
+  return concat(
+    [base, text(`ON CONFLICT (${conflictTarget}) DO UPDATE SET`), concat(sets, ", ")],
+    " ",
+  );
 }
 
 export function updateOf(
   table: TableDef,
+  target: string,
   patch: Record<string, unknown>,
   condition?: Condition,
   returning?: readonly string[],
@@ -124,17 +133,18 @@ export function updateOf(
         : param(value);
     return concat([text(`"${name}" =`), assigned], " ");
   });
-  const head = concat([text(`UPDATE "${table.name}" SET`), concat(sets, ", ")], " ");
+  const head = concat([text(`UPDATE ${target} SET`), concat(sets, ", ")], " ");
   const body = condition === undefined ? head : concat([head, text("WHERE"), condition], " ");
   return concat([body, returningClause(returning)], " ");
 }
 
 export function deleteOf(
   table: TableDef,
+  target: string,
   condition?: Condition,
   returning?: readonly string[],
 ): Fragment {
-  const head = text(`DELETE FROM "${table.name}"`);
+  const head = text(`DELETE FROM ${target}`);
   const body = condition === undefined ? head : concat([head, text("WHERE"), condition], " ");
   return concat([body, returningClause(returning)], " ");
 }

package/src/table/select.ts

@@ -122,6 +122,9 @@ export function selectQuery<T>(
     return undefined;
   };
 
+  // 表名按连接的方言算（PostgreSQL 带 schema）：FROM / JOIN 与其余引用保持同一处。
+  const targetOf = (definition: TableDef): string =>
+    database.dialect.tableName(definition.name, database.schema);
   const toFragment = (): Fragment => {
     const items = Object.entries(projection).map(([alias, entry]) =>
       entry.kind === "column"
@@ -133,13 +136,13 @@ export function selectQuery<T>(
     const parts: (Fragment | string)[] = [
       state.distinct ? text("SELECT DISTINCT") : text("SELECT"),
       concat(items, ", "),
-      text(`FROM "${table.name}"`),
+      text(`FROM ${targetOf(table)}`),
     ];
     for (const join of state.joins) {
       const target =
         join.alias === undefined
-          ? `"${join.table.name}"`
-          : `"${join.table.name}" AS "${join.alias}"`;
+          ? targetOf(join.table)
+          : `${targetOf(join.table)} AS "${join.alias}"`;
       if (join.kind === "cross") {
         parts.push(text(`CROSS JOIN ${target}`));
         continue;