SQL 模块

本模块为 XScript 提供轻量级关系型数据库访问能力。导出 API 以直接函数的形式提供，支持会话管理、查询/执行、异步推送、事务、结果缓存，以及新增的查询构建器与简易 ORM。说明与实现严格对齐。

引入

支持的后端与输入

驱动：MySQL、PostgreSQL（别名 pg ）、SQLite、TDengine（别名 taos ）、KingBase、Oracle

SQLite 连接：当类型为 sqlite 且 DSN 为空时，创建内存数据库

文件导入：当“类型”参数包含 .csv、.xls 或 .xlsx 时，将把该文件内容导入到一个 SQLite 数据库中供查询使用

快速开始

查询构建器

通过 sql.table(name, table) 获取链式查询构建器对象，支持 select、where、orderBy、limit、offset、get、first、count、toSQL。

sql.table(name, table): 返回构建器对象

select(...cols): 选择列；不调用则为 *

where(cond, ...args): 追加条件（自动拼接 AND）；参数按占位符 ? 填充

orderBy(field, dir?): 排序，dir 可选 ASC|DESC

limit(n), offset(n): 限制与偏移

get(): 返回数组结果集

first(): 返回首行或 null

count(): 返回 COUNT(*) 结果

toSQL(): 返回 { sql, args } 预览

示例：

注意：

where 支持多次调用，条件间以 AND 相连

参数为空字符串、null、undefined 将按实现行为转换为 NULL

ORM

通过 sql.model(name, table) 获取模型对象，提供常用 CRUD 包装。

find(where, ...args): 返回数组结果集

findOne(where, ...args): 返回首行或 null

findById(id): 按主键 id 查询首行

create(map): 插入记录；返回 lastInsertId（非 taosRestful）或 true

update(map, where?, ...args): 更新记录；返回 true|false

delete(where?, ...args): 删除记录；返回 true|false

示例：

缓存查询

sql.cache.query(name, ttlSeconds, stmt, ...args): 带缓存查询；键生成使用 FNV-1a 哈希；TTL 为秒

sql.cache.remove(name, stmt, ...args): 移除相应键

sql.cache.purge(name): 清空该会话缓存

sql.cache.list(name): 列出该会话的缓存键

示例：

使用示例与最佳实践

注意

大查询请务必使用过滤与分页，避免把结果完全加载到运行时

参数化查询可降低 SQL 注入风险

根据驱动不同，lastInsertId 行为可能存在差异（TDengine 不支持）

NoSQL 伪 SQL 适配层（MongoDB 与 Redis）

SQL 模块支持以统一的 SQL 语法操作 MongoDB 与 Redis，通过内置适配器完成语句解析与映射。

MongoDB（别名：`mgo`）

便捷方式（固定使用 mgo 驱动）：

通用方式（显式指定驱动）：

常用示例（集合名即 SQL 中的“表名”）：

说明：

WHERE 支持基础比较运算符：=, >, <, >=, <=, !=

支持 ORDER BY、LIMIT 与 OFFSET

复杂 JOIN/子查询不支持，建议使用 Mongo 原生聚合管道

Redis（别名：`rds`）

连接：

常用示例（专用表名 redis，通过 key 进行选择）：

说明：

Redis 适配层聚焦 key/value CRUD，不支持集合运算与事务

LastInsertId 在 rds 驱动中不适用，exec 返回布尔/受影响行数兼容行为

sql

SQL 模块#

引入#

支持的后端与输入#

快速开始#

查询构建器#

ORM#

缓存查询#

使用示例与最佳实践#

注意#

NoSQL 伪 SQL 适配层（MongoDB 与 Redis）#

MongoDB（别名：mgo）#

Redis（别名：rds）#