数据库原始查询

当数据模型 SDK 无法满足复杂查询需求时，可以直接使用 SQL 语句进行数据库操作。

此方法仅支持服务端调用

适用场景

• 复杂的多表联查
• 聚合函数和统计查询
• 数据库特定功能
• 性能优化查询

查询方法

MySQL 数据模型提供两种 SQL 查询方式：

方法	说明	安全性	推荐度
$runSQL	预编译模式，参数化查询	高（防SQL注入）	⭐⭐⭐
$runSQLRaw	原始模式，直接执行SQL	低（需自行防护）	⭐

⚠️ 重要提醒

• 仅支持服务端调用（云函数、云托管等）
• 当前仅支持 SELECT 语句
• 建议优先使用 $runSQL 预编译模式

初始化 SDK

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

1. 安装

npm install @cloudbase/node-sdk --save

2. 初始化

import cloudbase from "@cloudbase/node-sdk"

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

// 获取数据模型实例
const models = app.models

预编译模式 $runSQL

使用参数化查询，通过 Mustache 语法（ {{ }} ）绑定参数，有效防止 SQL 注入。

基础查询

// 条件查询
const result = await models.$runSQL(
    "SELECT * FROM `table_name` WHERE title = {{title}} LIMIT 10", {
        title: "hello"
    }
);

// 数值比较
const result = await models.$runSQL(
    "SELECT * FROM `table_name` WHERE read_num > {{num}}", {
        num: 1000
    }
);

// 时间查询
const result = await models.$runSQL(
    "SELECT * FROM `table_name` WHERE updatedAt > UNIX_TIMESTAMP({{timestamp}})", {
        timestamp: "2024-06-01 00:00:00"
    }
);

模糊查询和聚合

// LIKE 查询
const result = await models.$runSQL(
    "SELECT * FROM `table_name` WHERE author_tel LIKE {{tel}}", {
        tel: "1858%"
    }
);

// 聚合函数
const result = await models.$runSQL(
    "SELECT COUNT(*) FROM `table_name` WHERE is_published = {{isPublished}}", {
        isPublished: true
    }
);

// 指定字段
const result = await models.$runSQL(
    "SELECT read_num, title FROM `table_name`"
);

返回结果格式

// 成功返回示例
{
    "data": {
        "total": 1,
        "executeResultList": [{
            "_id": "9JXU7BWFZJ",
            "title": "hello",
            "read_num": 997,
            // ... 其他字段
        }],
        "backendExecute": "27"
    },
    "requestId": "16244844-19fe-4946-8924-d35408ced576"
}

原始模式 $runSQLRaw

用于动态表名等特殊场景，需要自行处理 SQL 注入防范。

基础用法

// 直接执行 SQL
const result = await models.$runSQLRaw(
    "SELECT * FROM `table_name` WHERE title = 'hello' LIMIT 10"
);

// 动态表名场景
const tableName = getTableName(); // 确保来源安全
const result = await models.$runSQLRaw(
    `SELECT * FROM \`${tableName}\` WHERE status = 'active'`
);

安全注意事项

使用 $runSQLRaw 时必须注意以下安全措施：

• 优先使用预编译模式：除非必要，建议使用 $runSQL
• 验证用户输入：严格验证和过滤所有用户输入
• 使用白名单：只允许预定义的安全值
• 转义特殊字符：特别注意单引号等 SQL 特殊字符
• 错误处理：避免暴露详细的数据库错误信息