SQL 模板
SQL 模板提供在 MySQL 数据模型上执行 SQL 命令的方式,支持参数化查询和权限控制,可在小程序端、Web 端安全调用。
基础使用
创建模板
在数据模型管理页面创建 SQL 模板:
- 模板名称:英文、数字、下划线组合,全局唯一
- SQL 命令:支持 SELECT、INSERT、UPDATE、DELETE、REPLACE INTO
- 描述:可选,记录模板用途
初始化 SDK
请参考 SDK 初始化 中 node-sdk 初始化方式进行初始化
- 安装
npm install @cloudbase/node-sdk --save
- 初始化
import cloudbase from "@cloudbase/node-sdk"
// 初始化应用
const app = cloudbase.init({
env: "your-env-id" // 替换为您的环境 ID
})
// 获取数据模型实例
const models = app.models
调用模板
调用sql模版
// 基础调用
const res = await app.models.modelName.runSQLTemplate({
templateName: 'template_name',
params: {
key: 'value'
}
});
// 指定环境
const res = await app.models.modelName.runSQLTemplate({
templateName: 'template_name',
envType: "pre", // pre: 体验环境, prod: 正式环境
params: {
key: 'value'
}
});
HTTP API 调用方式参考 HTTP API 文档
SQL 语句规范
支持的命令
- SELECT
- INSERT INTO
- REPLACE INTO
- UPDATE
- DELETE
基本规则
- 每个模板仅支持一条 SQL 命令
- 主表必须是当前模型的表
- 联表查询时子表可以是同库下任意表
- INSERT/REPLACE 操作必须包含 owner 和 _openid 系统字段
参数语法
使用 {{ param }}
语法引入变量参数:
SELECT * FROM {{ model.tableName() }}
WHERE status = {{ status }}
内置函数
类别 | 函数 | 说明 |
---|---|---|
模型 | model.tableName() | 获取当前模型表名 |
模型 | model.tableName('model_name') | 获取指定模型表名 |
模型 | model.dataId() | 生成数据ID |
用户 | user.userId() | 获取用户ID |
用户 | user.openId() | 获取用户openId |
权限 | auth.rowPermission() | 获取当前模型行权限 |
权限 | auth.rowPermission('model_name') | 获取指定模型行权限 |
系统 | system.currentEpoch() | 获取秒级时间戳 |
系统 | system.currentEpochMillis() | 获取毫秒级时间戳 |
最佳实践
表名引用
-- 使用当前模型表
SELECT * FROM {{ model.tableName() }}
-- 联表查询
SELECT a.*, b.*
FROM {{ model.tableName() }} a
JOIN {{ model.tableName('other_model') }} b
ON a.id = b.ref_id
数据操作
-- 插入数据
INSERT INTO {{ model.tableName() }}
(_id, name, owner, _openid, createBy, updatedAt)
VALUES (
{{ model.dataId() }},
{{ name }},
{{ user.userId() }},
{{ user.openId() }},
{{ user.userId() }},
{{ system.currentEpochMillis() }}
)
-- 更新数据
UPDATE {{ model.tableName() }}
SET name = {{ name }},
updatedAt = {{ system.currentEpochMillis() }}
WHERE _id = {{ id }}
AND {{ auth.rowPermission() }}
-- 查询数据
SELECT * FROM {{ model.tableName() }}
WHERE status = {{ status }}
AND {{ auth.rowPermission() }}
NULL 值处理
由于不支持 IS NULL 和 IS NOT NULL,使用以下替代语法:
-- 查询空值
WHERE column <=> NULL
-- 查询非空值
WHERE !(column <=> NULL)
注:更多高级用法和复杂查询示例,请参考SQL模板进阶指南