跳到主要内容

SQL 模板

SQL 模板提供在 MySQL 数据模型上执行 SQL 命令的方式,支持参数化查询和权限控制,可在小程序端、Web 端安全调用。

基础使用

创建模板

在数据模型管理页面创建 SQL 模板:

  • 模板名称:英文、数字、下划线组合,全局唯一
  • SQL 命令:支持 SELECT、INSERT、UPDATE、DELETE、REPLACE INTO
  • 描述:可选,记录模板用途

初始化 SDK

请参考 SDK 初始化node-sdk 初始化方式进行初始化

  1. 安装
npm install @cloudbase/node-sdk --save
  1. 初始化
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

基本规则

  1. 每个模板仅支持一条 SQL 命令
  2. 主表必须是当前模型的表
  3. 联表查询时子表可以是同库下任意表
  4. 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模板进阶指南