nodejs-store 2.0.3 → 2.1.0

package/README.md

@@ -98,7 +98,7 @@ Typical concrete scenarios (see [`doc/use-cases/`](doc/use-cases/) for full walk
 
 Being explicit about the boundary saves you time:
 
-- **You want a full ORM with a migration engine.** `nodejs-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`syncSchema` → introspection) but it never writes DDL back. Pair it with your migration tool of choice.
+- **You want a full ORM with a migration engine.** `nodejs-store` is a *data layer*, not a migration tool. It can **read** a SQL backend's physical structure (`syncSchema` → introspection) but it never writes DDL back. Pair it with your migration tool of choice. There is an optional `generateDdl()` that renders `CREATE TABLE` text from your registered schemas — pure text, it never connects to or writes to the database.
 - **You need a type-safe generated client.** Schemas are runtime JSON, not TypeScript types. You get flexibility and cross-language parity (same schema runs in Node and Python), not compile-time type inference.
 - **You only ever use one database and rarely join.** A plain driver (or a single-database ODM/ORM) will be simpler.
 - **You need raw aggregation escape hatches.** `$pipeline` passthrough and `store.aggregate()` were deliberately removed. Use `$condition` / `$group` / `$having` / relations; anything that cannot be safely translated fails **explicitly** rather than silently.
@@ -117,7 +117,7 @@ General positioning, not a benchmark — always verify against each tool's curre
 | Built-in role / field-level RBAC + owner injection | ✅ | ➖ | ➖ (via extensions) | ➖ | ➖ |
 | Read-time computed columns (sync / async / relation-agg) | ✅ | ➖ (getters) | ➖ | ➖ | ➖ |
 | Soft-delete archive table auto-provisioned | ✅ | ➖ | ➖ | ➖ | ➖ |
-| Migration / DDL engine | ➖ (introspection read-only) | ➖ | ✅ | ✅ | ✅ |
+| Migration / DDL engine | ➖ (introspection read-only; optional `generateDdl` text) | ➖ | ✅ | ✅ | ✅ |
 | Static type generation | ➖ (runtime JSON, cross-language parity) | ➖ | ✅ | ⚠️ (decorators + TS) | ✅ |
 | Shared native core across Node & Python | ✅ (Rust `rust-store`) | ➖ | ➖ | ➖ | ➖ |
 
@@ -128,7 +128,7 @@ Positioning only, based on those projects' public documentation at the time of w
 - **vs Mongoose** — Mongoose is MongoDB-only. `nodejs-store` uses a similar MongoDB-style query syntax (`$gt`, `$or`, `$set`, `$inc`) but the same query also runs unchanged against MySQL, SQLite and PostgreSQL.
 - **vs `mongoosql-core`** — the closest in spirit: it also runs Mongoose-style queries on MongoDB, PostgreSQL and MySQL. `nodejs-store` additionally targets SQLite, ships schema-level permissions (role/field whitelists plus `creator` owner-condition injection), read-time computed columns (`fn` / `asyncFn` / relation-`agg`), an auto-provisioned `<Model>Deleted` soft-delete archive, and shares one Rust engine with a Python host so Node.js and Python cannot drift apart.
 - **vs `unsql`** — `unsql` generates SQL from plain JavaScript objects for MySQL, PostgreSQL and SQLite. It does not target MongoDB, and it is a query/CRUD helper rather than a schema-driven data layer with permissions and computed columns.
-- **vs Prisma** — Prisma is a schema DSL plus generated client with a migration engine and compile-time types. `nodejs-store` is a runtime JSON schema with no DDL or migration responsibility (it only *reads* physical structure via introspection) and no type generation — in exchange for one query dialect spanning a document store and three relational stores.
+- **vs Prisma** — Prisma is a schema DSL plus generated client with a migration engine and compile-time types. `nodejs-store` is a runtime JSON schema with no migration engine (it only *reads* physical structure via introspection, and `generateDdl()` only *renders* `CREATE TABLE` text without touching the database) and no type generation — in exchange for one query dialect spanning a document store and three relational stores.
 - **vs TypeORM / Sequelize / Drizzle** — Sequelize and Drizzle are SQL-only; TypeORM models MongoDB separately from its SQL entities. `nodejs-store` treats MongoDB as the primary dialect and compiles the same GQL to SQL for the other three backends.
 
 Short version: use an ORM when you want **compile-time types and migrations**; use `nodejs-store` when you want **one runtime schema + one query dialect spanning MongoDB and SQL**, with RBAC and computed columns built in.
@@ -302,6 +302,38 @@ Notes:
 - `queryWithCount` accepts `page`/`pageSize` (recommended) or the traditional `$skip`/`$limit` params.
 - `updateMany` / `remove` with an **empty condition** (`{}`, `null`, `{ "$and": [] }`) is rejected outright — it never falls through to a full-table write.
 
+### Transactions and raw SQL
+
+```js
+async function transfer() {
+  const rows = await store.executeRaw(
+    'default', 'SELECT * FROM accounts WHERE _id = ? FOR UPDATE', [accId]);
+  await store.executeRaw(
+    'default', 'UPDATE accounts SET balance = ? WHERE _id = ?', [newBalance, accId],
+    true);
+}
+
+await store.transaction('default', transfer);
+```
+
+- `store.transaction(source, fn)` opens a transaction scope on one SQL source: every `executeRaw` / CRUD call inside `fn` lands on that source's transaction connection, with `commit` / `rollback` as one unit (reuses the internal `runInTransaction`). Mongo sources or executors without transactions run `fn` as-is — it never pretends to be atomic.
+- `store.executeRaw(source, sql, params, isWrite)` runs raw SQL, bypassing GQL parsing and dialect translation. Placeholders follow each backend's native style: `?` for MySQL / SQLite, `$1..$n` for PostgreSQL. SQL sources only — a Mongo source throws `RawSqlError` (`store.RawSqlError`).
+- `isWrite=false` (default) returns `{ rows, affectedRows }` with the result-set rows; `isWrite=true` returns the affected-row count.
+
+### DDL generation
+
+```js
+let sql = store.generateDdl('mysql');                       // every registered model
+sql     = store.generateDdl('postgres', ['Course', 'CourseDeleted']);
+```
+
+`store.generateDdl(backend, names)` maps one registered schema def to one `CREATE TABLE` — the inverse of `syncSchema()`, which only *reads*. The generator is **pure text**: it never connects to, or writes to, the database (iron rule 6 still holds).
+
+- Only scalar fields become columns; `object` / `array` fields do not.
+- Every table gets the `__present` sentinel column; `timestamps` models also get `createdAt` / `updatedAt`; the `<collection>_deleted` archive table is generated like any other registered def.
+- No `CREATE INDEX` is emitted — SQL backends keep indexes as metadata only.
+- MySQL `__present` is `VARCHAR(255)`; a schema whose present-token string would overflow emits a `ddlPresentOverflow` feedback event rather than failing silently.
+
 ## Multi-datasource connections
 
 Every schema is located by the triple `(source, namespace, collection)` — the triple must be
@@ -528,7 +560,7 @@ Every registered model automatically gets a `<Model>Deleted` archive collection/
 Yes. Bind a schema to `(source, namespace, collection)` and pass a `{ source, namespace }` route override per request. Treat `routeOverride` as trusted server-side input only.
 
 **Does it run migrations?**
-No. `syncSchema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job.
+No. `syncSchema()` only *reads* physical structure via introspection (introspect → merge overlay → register). Schema changes / DDL are your migration tool's job. If you want a starting point, `store.generateDdl(backend)` renders `CREATE TABLE` text from the registered schemas — but it is pure text generation: it never runs or writes DDL.
 
 **Can I see the generated query without running it?**
 Yes — `store.buildPipeline(gql, params)` returns the compiled plan (`{ tokens, ast, pipeline, projection }`) with no execution and no permission/compute application.

package/README.zh-CN.md

@@ -97,7 +97,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 
 明确边界能为你省下时间：
 
-- **你想要带迁移引擎的完整 ORM。** `nodejs-store` 是*数据层*，不是迁移工具。它可以**读取** SQL 后端的物理结构（`syncSchema` → introspection），但从不把 DDL 写回。请与你自选的迁移工具搭配使用。
+- **你想要带迁移引擎的完整 ORM。** `nodejs-store` 是*数据层*，不是迁移工具。它可以**读取** SQL 后端的物理结构（`syncSchema` → introspection），但从不把 DDL 写回。请与你自选的迁移工具搭配使用。另有一个可选的 `generateDdl()`，可从已注册 schema 渲染出 `CREATE TABLE` 文本 —— 纯文本，绝不连接或写入数据库。
 - **你需要带类型安全、自动生成的客户端。** schema 是运行时 JSON，而非 TypeScript 类型。你获得的是灵活性与跨语言一致性（同一份 schema 在 Node 与 Python 中都可用），而不是编译期类型推断。
 - **你只用一种数据库，且几乎不做关联。** 直接用裸驱动（或只针对单一数据库的 ODM/ORM）会更简单。
 - **你需要原生聚合逃生舱。** `$pipeline` 透传与 `store.aggregate()` 已被有意移除。请使用 `$condition` / `$group` / `$having` / 关系；任何无法安全翻译的内容都会**显式**失败，而不会静默降级。
@@ -116,7 +116,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 | 内置角色 / 字段级 RBAC + 属主注入 | ✅ | ➖ | ➖（通过扩展） | ➖ | ➖ |
 | 读时计算列（同步 / 异步 / 关系聚合） | ✅ | ➖（getter） | ➖ | ➖ | ➖ |
 | 自动置备软删除归档表 | ✅ | ➖ | ➖ | ➖ | ➖ |
-| 迁移 / DDL 引擎 | ➖（introspection 只读） | ➖ | ✅ | ✅ | ✅ |
+| 迁移 / DDL 引擎 | ➖（introspection 只读；可选 `generateDdl` 文本） | ➖ | ✅ | ✅ | ✅ |
 | 静态类型生成 | ➖（运行时 JSON，跨语言一致） | ➖ | ✅ | ⚠️（装饰器 + TS） | ✅ |
 | Node 与 Python 共享原生核心 | ✅（Rust `rust-store`） | ➖ | ➖ | ➖ | ➖ |
 
@@ -127,7 +127,7 @@ MongoDB 是*主方言*：查询以 MongoDB 风格的 GQL 编写，三种关系
 - **vs Mongoose** —— Mongoose 仅支持 MongoDB。`nodejs-store` 使用类似的 MongoDB 风格查询语法（`$gt`、`$or`、`$set`、`$inc`），但同一条查询也能原样跑在 MySQL、SQLite 与 PostgreSQL 上。
 - **vs `mongoosql-core`** —— 精神上最接近：它同样能在 MongoDB、PostgreSQL 与 MySQL 上运行 Mongoose 风格的查询。`nodejs-store` 还额外面向 SQLite，内置 schema 级权限（角色/字段白名单，外加 `creator` 属主条件注入）、读时计算列（`fn` / `asyncFn` / 关系 `agg`）、自动置备的 `<Model>Deleted` 软删除归档，并与 Python 宿主共享同一个 Rust 引擎，因此 Node.js 与 Python 不会产生漂移。
 - **vs `unsql`** —— `unsql` 从普通 JavaScript 对象为 MySQL、PostgreSQL 与 SQLite 生成 SQL。它不面向 MongoDB，且只是一个查询/CRUD 辅助工具，而非带权限与计算列的 schema 驱动数据层。
-- **vs Prisma** —— Prisma 是 schema DSL 加生成的客户端，配有迁移引擎与编译期类型。`nodejs-store` 是运行时 JSON schema，不承担 DDL 或迁移职责（仅通过 introspection *读取*物理结构），也不生成类型 —— 以此换取一套横跨文档库与三种关系库的查询方言。
+- **vs Prisma** —— Prisma 是 schema DSL 加生成的客户端，配有迁移引擎与编译期类型。`nodejs-store` 是运行时 JSON schema，不承担迁移引擎职责（仅通过 introspection *读取*物理结构，`generateDdl()` 也只*渲染* `CREATE TABLE` 文本而不触碰数据库），也不生成类型 —— 以此换取一套横跨文档库与三种关系库的查询方言。
 - **vs TypeORM / Sequelize / Drizzle** —— Sequelize 与 Drizzle 仅支持 SQL；TypeORM 把 MongoDB 与其 SQL 实体分开建模。`nodejs-store` 以 MongoDB 为主方言，并把同一份 GQL 编译为其余三种后端的 SQL。
 
 一句话：想要**编译期类型与迁移**就用 ORM；想要**一份运行时 schema + 一套横跨 MongoDB 与 SQL 的查询方言**，并内置 RBAC 与计算列，就用 `nodejs-store`。
@@ -301,6 +301,38 @@ await store.upsert('Post', { code: 'A1' }, { ... });      // 显式条件的 ups
 - `queryWithCount` 接受 `page`/`pageSize`（推荐）或传统的 `$skip`/`$limit` 参数。
 - 带**空条件**（`{}`、`null`、`{ "$and": [] }`）的 `updateMany` / `remove` 会被直接拒绝 —— 它绝不会退化为全表写入。
 
+### 事务与原生 SQL
+
+```js
+async function transfer() {
+  const rows = await store.executeRaw(
+    'default', 'SELECT * FROM accounts WHERE _id = ? FOR UPDATE', [accId]);
+  await store.executeRaw(
+    'default', 'UPDATE accounts SET balance = ? WHERE _id = ?', [newBalance, accId],
+    true);
+}
+
+await store.transaction('default', transfer);
+```
+
+- `store.transaction(source, fn)` 在单个 SQL 源上开启事务作用域：`fn` 内的每个 `executeRaw` / CRUD 调用都落到该源的事务连接，`commit` / `rollback` 作为一个整体（复用内部的 `runInTransaction`）。Mongo 源或不支持事务的执行器会按原样执行 `fn` —— 绝不假装已原子。
+- `store.executeRaw(source, sql, params, isWrite)` 执行原生 SQL，绕开 GQL 解析与方言翻译。占位符沿用各后端原生风格：MySQL / SQLite 用 `?`，PostgreSQL 用 `$1..$n`。仅限 SQL 源 —— Mongo 源会抛出 `RawSqlError`（`store.RawSqlError`）。
+- `isWrite=false`（默认）返回 `{ rows, affectedRows }` 含结果集行；`isWrite=true` 返回影响行数。
+
+### DDL 生成
+
+```js
+let sql = store.generateDdl('mysql');                       // 所有已注册模型
+sql     = store.generateDdl('postgres', ['Course', 'CourseDeleted']);
+```
+
+`store.generateDdl(backend, names)` 把一个已注册 schema def 映射为一条 `CREATE TABLE` —— 是 `syncSchema()`（只*读取*）的逆操作。生成器是**纯文本**：它绝不连接、也绝不写入数据库（铁律 6 依然成立）。
+
+- 只有标量字段成为列；`object` / `array` 字段不建列。
+- 每张表都会获得 `__present` 哨兵列；`timestamps` 模型还会获得 `createdAt` / `updatedAt`；`<collection>_deleted` 归档表与其它已注册 def 一样生成。
+- 不生成 `CREATE INDEX` —— SQL 后端仅把索引保留为元数据。
+- MySQL 的 `__present` 为 `VARCHAR(255)`；若某 schema 的 present 令牌串会超限，则发出 `ddlPresentOverflow` 反馈事件，而非静默失败。
+
 ## 多数据源连接
 
 每个 schema 由三元组 `(source, namespace, collection)` 定位 —— 该三元组在 registry 内必须
@@ -525,7 +557,7 @@ await init({ default: db, pg_a: executors.createConnection('postgres', pgPool) }
 可以。把 schema 绑定到 `(source, namespace, collection)`，并按请求传入 `{ source, namespace }` 路由覆盖。仅把 `routeOverride` 当作受信的服务端输入。
 
 **它会执行迁移吗？**
-不会。`syncSchema()` 只通过 introspection *读取*物理结构（introspect → 合并 overlay → 注册）。schema 变更 / DDL 是你所用迁移工具的职责。
+不会。`syncSchema()` 只通过 introspection *读取*物理结构（introspect → 合并 overlay → 注册）。schema 变更 / DDL 是你所用迁移工具的职责。若想要一个起点，`store.generateDdl(backend)` 可从已注册 schema 渲染 `CREATE TABLE` 文本 —— 但它只是纯文本生成：绝不执行、也不写入 DDL。
 
 **能否在不运行的情况下查看生成的查询？**
 可以 —— `store.buildPipeline(gql, params)` 返回编译后的计划（`{ tokens, ast, pipeline, projection }`），不执行，也不应用权限/计算列。

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "nodejs-store",
-  "version": "2.0.3",
+  "version": "2.1.0",
   "description": "Multi-backend data layer for Node.js (MongoDB, MySQL, SQLite, PostgreSQL): pure JSON schemas, GQL tree queries compiled to a single native query, GROUP BY/HAVING aggregation, computed columns, soft-delete and role-based access control",
   "main": "src/index.js",
-  "homepage": "https://coenddt.github.io/nodejs-store/",
   "files": [
     "src",
     "README.md",
@@ -57,7 +56,7 @@
   "bugs": {
     "url": "https://github.com/coenddt/nodejs-store/issues"
   },
-  "homepage": "https://github.com/coenddt/nodejs-store#readme",
+  "homepage": "https://coenddt.github.io/nodejs-store/",
   "engines": {
     "node": ">=18"
   },

package/src/datasource.js

@@ -235,6 +235,39 @@ async function execSql(source, connection, cmd) {
   return executors.shapeResult(cmd, out);
 }
 
+/** 原生 SQL 入口的显式错误（非 SQL 源 / 执行器未接入） */
+class RawSqlError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'RawSqlError';
+  }
+}
+
+/**
+ * 在指定 SQL 源上执行原生 SQL（Host 层逃生口，绕开 core 的 dialectTranslate）
+ *
+ *   - 事务作用域内经 `connectionFor` 落到事务专用连接 → 支持 SELECT ... FOR UPDATE；
+ *   - 占位符沿用各后端原生风格（mysql/sqlite 用 `?`，postgres 用 `$1..$n`）；
+ *   - 仅支持 SQL 源；Mongo 源显式报错（绝不静默）；
+ *   - `isWrite=false` 视为读（取行）；`true` 视为写（取影响行数）；
+ *   - 返回 `{ rows, affectedRows }`。
+ *   对齐 py_store/datasource.py#execute_raw。
+ */
+async function executeRaw(source, sql, params = [], isWrite = false) {
+  const conn = connectionFor(source);
+  if (!conn || typeof conn.kind !== 'string') {
+    throw new RawSqlError(
+      `数据源 ${source} 不是 SQL 源（原生 SQL 入口仅支持 mysql/postgres/sqlite）`,
+    );
+  }
+  if (typeof conn.exec !== 'function') {
+    throw new RawSqlError(`SQL 数据源 ${source}(${conn.kind}) 的执行器未接入`);
+  }
+  const stmt = { text: sql, params: Array.from(params || []), isWrite: Boolean(isWrite) };
+  const out = await conn.exec({ stmts: [stmt] });
+  return { rows: out.rows ?? null, affectedRows: Number(out.affectedRows || 0) };
+}
+
 module.exports = {
   DEFAULT_SOURCE,
   setConnections,
@@ -250,5 +283,7 @@ module.exports = {
   dbOfSchema,
   route,
   execSql,
+  executeRaw,
   PushdownUnsupportedError,
+  RawSqlError,
 };

package/src/ddl.js

@@ -0,0 +1,124 @@
+'use strict';
+
+/**
+ * DDL 生成（schema def → CREATE TABLE 文本；纯函数，不连库、不回写）
+ *
+ * 与 core 契约严格对齐（schema→DDL 单向映射）：
+ *   - 只对 scalar 字段建列（object/array 不建列；同 core dialect::scalar_column）；
+ *   - 每表必建 __present 哨兵列（形态 ,f1,f2,；同 core write/insert.rs::present_value）；
+ *   - timestamps !== false → 追加 createdAt / updatedAt（同 core schema/registry.rs::add_timestamp_fields）；
+ *   - 归档表 <collection>_deleted 由 registry 自动派生，本模块按已注册 def 逐表生成（不特判）；
+ *   - 不生成 CREATE INDEX（SQL 后端不建索引，schema.indexes 仅元数据，铁律 6）。
+ *
+ * 生成器只产出文本、不执行 —— 不违反铁律 6（绝不写 DDL 回库）。
+ * 对齐 py_store/ddl.py（两端输出逐字节一致）。
+ */
+
+const { emit: _emitFeedback } = require('./feedback');
+const schema = require('./schema');
+
+const BACKENDS = ['mysql', 'postgres', 'sqlite'];
+
+// schema 声明类型 → [mysql, postgres, sqlite] 列类型
+const TYPES = {
+  string: ['VARCHAR(255)', 'TEXT', 'TEXT'],
+  int: ['INT', 'INTEGER', 'INTEGER'],
+  long: ['BIGINT', 'BIGINT', 'INTEGER'],
+  number: ['BIGINT', 'BIGINT', 'INTEGER'],
+  float: ['DOUBLE', 'DOUBLE PRECISION', 'REAL'],
+  double: ['DOUBLE', 'DOUBLE PRECISION', 'REAL'],
+  bool: ['TINYINT(1)', 'BOOLEAN', 'INTEGER'],
+  boolean: ['TINYINT(1)', 'BOOLEAN', 'INTEGER'],
+  datetime: ['BIGINT', 'BIGINT', 'INTEGER'],
+  date: ['BIGINT', 'BIGINT', 'INTEGER'],
+};
+const NON_COLUMN = ['object', 'array'];
+const ID_TYPE = ['VARCHAR(64)', 'TEXT', 'TEXT'];
+const PRESENT_TYPE = ['VARCHAR(255)', 'TEXT', 'TEXT'];
+const TIMESTAMP_FIELDS = ['createdAt', 'updatedAt'];
+const MYSQL_PRESENT_MAX = 255;
+
+function idx(backend) {
+  return BACKENDS.indexOf(backend);
+}
+
+/** 标识符引用（与 core Backend::quote_ident 一致：mysql 反引号，其余双引号） */
+function q(backend, ident) {
+  if (backend === 'mysql') return '`' + ident.replace(/`/g, '``') + '`';
+  return '"' + ident.replace(/"/g, '""') + '"';
+}
+
+function declaredType(fieldDef) {
+  return fieldDef && typeof fieldDef === 'object' ? fieldDef.type : fieldDef;
+}
+
+/** 返回 [[name, sqlType, pk]]，顺序：声明的标量字段 → timestamps → __present */
+function columns(defn, backend) {
+  const i = idx(backend);
+  const cols = [];
+  const fields = defn.fields || {};
+  for (const [name, fdef] of Object.entries(fields)) {
+    const ftype = declaredType(fdef);
+    if (NON_COLUMN.includes(ftype)) continue;
+    if (name === '_id') {
+      cols.push([name, ID_TYPE[i], true]);
+      continue;
+    }
+    if (!Object.prototype.hasOwnProperty.call(TYPES, ftype)) {
+      throw new Error(
+        `DDL 生成：字段 "${defn.name}.${name}" 类型 ${JSON.stringify(ftype)} 未知，支持 ${Object.keys(TYPES).sort()}`,
+      );
+    }
+    cols.push([name, TYPES[ftype][i], false]);
+  }
+  if (!cols.some((c) => c[2])) {
+    throw new Error(`DDL 生成：schema "${defn.name}" 缺少 _id 字段`);
+  }
+  if (defn.timestamps !== false) {
+    for (const ts of TIMESTAMP_FIELDS) {
+      if (!cols.some((c) => c[0] === ts)) cols.push([ts, TYPES.number[i], false]);
+    }
+  }
+  cols.push(['__present', PRESENT_TYPE[i], false]);
+  return cols;
+}
+
+/** MySQL __present VARCHAR(255) 容量校验：超限即告警（不静默） */
+function warnPresentOverflow(defn, cols) {
+  const length = cols.reduce((n, c) => n + c[0].length, 0) + cols.length + 1;
+  if (length > MYSQL_PRESENT_MAX) {
+    _emitFeedback({
+      type: 'ddl_present_overflow',
+      code: 'ddlPresentOverflow',
+      layer: 'host',
+      message: `表 ${defn.collection} 的 __present 预估长度 ${length} 超过 MySQL VARCHAR(255)`,
+      hint: '为该表改用 TEXT 列，或减少标量字段；否则写入会被截断/报错，导致 $eq:null / $exists 三态判定错误',
+      schema: defn.name,
+    });
+  }
+}
+
+function createTable(defn, backend) {
+  const table = defn.collection || defn.name;
+  const cols = columns(defn, backend);
+  if (backend === 'mysql') warnPresentOverflow(defn, cols);
+  const lines = [];
+  for (const [name, ctype, pk] of cols) {
+    if (pk && backend === 'mysql') lines.push(`  ${q(backend, name)} ${ctype} NOT NULL`);
+    else if (pk) lines.push(`  ${q(backend, name)} ${ctype} PRIMARY KEY`);
+    else lines.push(`  ${q(backend, name)} ${ctype}`);
+  }
+  if (backend === 'mysql') lines.push(`  PRIMARY KEY (${q(backend, '_id')})`);
+  return `CREATE TABLE ${q(backend, table)} (\n` + lines.join(',\n') + '\n);';
+}
+
+/** 生成 DDL 文本（多表以空行分隔）；backend ∈ mysql/postgres/sqlite */
+function generate(backend, names) {
+  if (!BACKENDS.includes(backend)) {
+    throw new Error(`DDL 生成：不支持的后端 ${JSON.stringify(backend)}（支持 ${BACKENDS.join('/')}）`);
+  }
+  const targets = names && names.length ? Array.from(names) : schema.list();
+  return targets.map((n) => createTable(schema.get(n), backend)).join('\n\n');
+}
+
+module.exports = { generate };

package/src/index.js

@@ -23,6 +23,7 @@
 
 const crud = require('./crud');
 const datasource = require('./datasource');
+const ddl = require('./ddl');
 const executors = require('./executors');
 const feedback = require('./feedback');
 const introspect = require('./introspect');
@@ -113,6 +114,33 @@ class Store {
     return syncSchema(opts);
   }
 
+  // ── 事务 + 原生 SQL（复用 datasource.runInTransaction；见 README「事务边界」）──
+  /**
+   * 事务作用域：单 SQL 源「同连接 + 同事务」执行 fn（复用 runInTransaction）
+   *
+   * fn 内 executeRaw / CRUD 均落到该源的事务连接（commit/rollback 一体）；
+   * Mongo 源或执行器未实现 withTransaction 时按原样执行（跨源无法原子），
+   * 绝不静默假装已事务化。单源场景 source 传 'default'。
+   */
+  async transaction(source, fn) {
+    return datasource.runInTransaction(source, fn);
+  }
+
+  /**
+   * 在指定 SQL 源执行原生 SQL（事务内可用；占位符按各后端原生风格）
+   *
+   * mysql/sqlite 用 `?`，postgres 用 `$1..$n`；仅支持 SQL 源（Mongo 源抛 RawSqlError）。
+   * isWrite=false 取行（rows），true 取影响行数（affectedRows）。对齐 py-store store.execute_raw。
+   */
+  async executeRaw(source, sql, params, isWrite) {
+    return datasource.executeRaw(source, sql, params, isWrite);
+  }
+
+  /** 从已注册 schema def 生成指定后端 DDL 文本（纯函数，不连库、不回写；铁律 6） */
+  generateDdl(backend, names) {
+    return ddl.generate(backend, names);
+  }
+
   // ── 底层工具（调试/高级用法） ──
   /** 解析 GQL 并构建 pipeline，返回 `{tokens, ast, pipeline, projection}` */
   buildPipeline(gql, params) {
@@ -163,6 +191,8 @@ class Store {
 
 /** 自定义权限错误（实例可被 store.PermissionError 捕获） */
 Store.prototype.PermissionError = permission.PermissionError;
+/** 原生 SQL 入口错误（实例可被 store.RawSqlError 捕获） */
+Store.prototype.RawSqlError = datasource.RawSqlError;
 
 const store = new Store();
 
@@ -255,7 +285,9 @@ module.exports = {
   Store,
   PermissionError: permission.PermissionError,
   PushdownUnsupportedError: datasource.PushdownUnsupportedError,
+  RawSqlError: datasource.RawSqlError,
   datasource,
+  ddl,
   schema,
   permission,
   crud,