SQL 模板

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

基础使用

创建模板

进入 云开发平台/MySQL数据库/数据模型 ，选择对应数据模型，点击「SQL模版管理」标签页，点击「新建」按钮即可。

调用 SQL 模版

选择对应 SDK 进行调用：

SDK 类型	适用平台
Web SDK	Web 浏览器
Node.js SDK	Node.js 环境

调用示例

以 Node.js SDK 为例，调用示例代码如下：

import cloudbase from "@cloudbase/node-sdk";

// 初始化应用
const app = cloudbase.init({
  env: "your-env-id", // 替换为您的环境 ID
});

// 调用 user 表的 SQL 模版
const res = await app.models.user.runSQLTemplate({
  templateName: "template_name",
  params: {
    key: "value",
  },
});

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 }}

内置函数

SQL 模板支持以下内置函数，可在模板中直接使用：

类别	函数	说明
模型	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)