api
SQL
查看 MarkdownKasumi TypeScript SQL API、参数守卫和错误行为
在 TypeScript 中查询数据库驱动、打开连接、执行参数化语句并关闭连接。
KSM.sql 只封装 SQL 插件的前端调用，不实现数据库协议、SQL 方言转换或 ORM。实际可用
驱动由宿主返回；SQLite 在 Windows 和 Android 中内置。Windows 还会发现系统 MySQL /
MariaDB 和 PostgreSQL ODBC 驱动，MongoDB 与 Android 远程数据库需要宿主注册驱动。
实现入口是 frontend/src/api/sql.ts 和 frontend/src/api/guards.ts。所有语句都必须
经过参数守卫，宿主仍会执行 schema、权限和驱动级校验。
| 能力 | Windows | Android |
|---|---|---|
| SQL 五个命令 | 支持 | 支持 |
| SQLite | 内置 | 内置 |
| MySQL / PostgreSQL | 系统 ODBC 驱动存在时支持 | 注册驱动后支持 |
| MongoDB | 注册驱动后支持 | 注册驱动后支持 |
sql.drivers 返回的数组是唯一可靠的运行时能力来源。不要根据协议枚举假定驱动已安装。
drivers()const { drivers } = await KSM.sql.drivers();返回 { drivers: KSMSqlDriver[] }。可能包含 sqlite、mysql、postgres 和
mongodb 中的任意子集。
open({ driver, url })const { connectionId } = await KSM.sql.open({
driver: 'sqlite',
url: ':memory:'
});创建独立连接。driver 必须属于 sqlite | mysql | postgres | mongodb，url 必须是非
空字符串且不超过 4096 字符。URL 的具体格式由驱动定义。
query({ connectionId, statement, params? })const result = await KSM.sql.query({
connectionId,
statement: 'SELECT id, body FROM notes WHERE id = ?',
params: [1]
});返回 { columns, rows }。rows 是列名到标量值的对象数组。语句必须使用目标驱动的占位符，
不得拼接未转义的用户输入。
execute({ connectionId, statement, params? })const result = await KSM.sql.execute({
connectionId,
statement: 'UPDATE notes SET body = ? WHERE id = ?',
params: ['updated', 1]
});返回 { rowsAffected, lastInsertId }。lastInsertId 可能为 null。
close({ connectionId })await KSM.sql.close({ connectionId });关闭后连接 ID 失效，再次使用返回 NOT_FOUND。
前端会在发送请求前拒绝：
connectionId 或超过 128 字符的连接 ID。params。null 之外的参数。这些失败通常是普通 TypeError。绕过前端封装直接调用 KSM.invoke() 时，宿主返回
INVALID_ARGS。
import { KSM } from '@kasumi/bridge';
const { drivers } = await KSM.sql.drivers();
if (!drivers.includes('sqlite')) {
throw new Error('SQLite driver missing');
}
const { connectionId } = await KSM.sql.open({
driver: 'sqlite',
url: 'app://data/app.db'
});
try {
await KSM.sql.execute({
connectionId,
statement: 'CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL)'
});
await KSM.sql.execute({
connectionId,
statement: 'INSERT INTO notes (body) VALUES (?)',
params: ['hello']
});
const result = await KSM.sql.query({
connectionId,
statement: 'SELECT id, body FROM notes ORDER BY id'
});
console.info(result.rows);
} finally {
await KSM.sql.close({ connectionId });
}| 错误码 | 场景 |
|---|---|
INVALID_ARGS | 参数结构、语句语法或驱动 URL 非法 |
PERMISSION_DENIED | 路径、业务授权或驱动策略拒绝 |
NOT_FOUND | 连接 ID 不存在或已关闭 |
IO_ERROR | 打开、网络、磁盘或执行失败 |
NOT_SUPPORTED | 驱动未注册或平台不支持 |
TIMEOUT | 请求超过 10 秒默认超时 |
CANCELLED | 请求被取消 |
SQL 请求复用 KSM.invoke 的超时与取消链路。长查询应在业务层控制语句范围；当前 API
不提供进度事件、事务对象或公开 AbortSignal。
KSM.sql.drivers()，确认驱动存在。app://data、app://cache 或 app://tmp。finally 中关闭，页面销毁后不得复用旧连接 ID。
评论