关系型数据库（MySQL）

版本提示

自 v5.0.0 起新增此模块。通过 app.mysql 访问，提供云开发托管 MySQL（Serverless CynosDB）数据库的完整管理能力。

---

初始化

import CloudBase from '@cloudbase/manager-node'

const app = CloudBase.init({
  secretId: 'Your SecretId',
  secretKey: 'Your SecretKey',
  envId: 'Your envId'
})

const mysql = app.mysql

---

createMySQL

1. 接口描述

接口功能：为当前环境开通 MySQL 数据库

接口声明：app.mysql.createMySQL(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
DbInstanceType	否	String	Db 类型，固定值 MYSQL
MysqlVersion	否	String	MySQL 版本，如 5.7
VpcId	否	String	VPC ID
SubnetId	否	String	子网 ID
LowerCaseTableNames	否	String	表名大小写：0（区分）/ 1（不区分，默认）

3. 返回结果

字段	类型	说明
RequestId	String	请求唯一标识
Data.TaskId	String	异步开通任务 ID

4. 示例代码

const { Data } = await mysql.createMySQL({ MysqlVersion: '5.7' })
console.log('开通任务 ID:', Data.TaskId)

---

describeCreateResult

1. 接口描述

接口功能：查询 MySQL 开通状态

接口声明：app.mysql.describeCreateResult(options?): Promise<Object>

2. 返回结果

字段	类型	说明
Data.Status	String	notexist（未开通）/ success（已开通）
Data.FailReason	String	失败原因（失败时有值）
Data.FreezeStatus	Boolean	是否冻结

---

describeClusterDetail

1. 接口描述

接口功能：查询 MySQL 集群详情（数据库信息、网络配置等）

接口声明：app.mysql.describeClusterDetail(): Promise<Object>

2. 返回结果

字段	类型	说明
Data.DbClusterId	String	集群 ID
Data.DbInfo	Object	数据库状态、版本、存储等信息
Data.NetInfo	Object	内外网 IP、VPC 等网络信息

---

destroyMySQL

1. 接口描述

接口功能：销毁当前环境的 MySQL 实例

接口声明：app.mysql.destroyMySQL(): Promise<Object>

2. 返回结果

字段	类型	说明
Data.IsSuccess	Boolean	是否成功
Data.TaskId	String	任务 ID
Data.TaskName	String	任务名称

---

describeTaskStatus

1. 接口描述

接口功能：查询 MySQL 异步任务状态

接口声明：app.mysql.describeTaskStatus(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
TaskId	否	String	任务 ID

3. 返回结果

字段	类型	说明
Status	String	任务状态，如 SUCCESS / FAILED
StatusDesc	String	状态描述

---

runSql

1. 接口描述

接口功能：直接执行 SQL 语句（SELECT/INSERT/UPDATE/DELETE 等）

接口声明：app.mysql.runSql(options): Promise<IRunSqlResult>

2. 输入参数

字段	必填	类型	说明
Sql	是	String	要执行的 SQL 语句
DbInstance	否	Object	数据库连接器实例信息
ReadOnly	否	Boolean	只读模式（仅允许 SELECT/WITH/SHOW/DESCRIBE/EXPLAIN 语句）

3. 返回结果

字段	类型	说明
Items	String[]	查询结果行（每行为 JSON 字符串）
Infos	String[]	列元数据
RowsAffected	Number	受影响的行数
RequestId	String	请求唯一标识

4. 示例代码

const res = await mysql.runSql({
  Sql: 'SELECT * FROM users WHERE id = 1'
})
const rows = res.Items.map(item => JSON.parse(item))
console.log(rows)

---

openWan / closeWan

1. 接口描述

接口功能：开启/关闭实例的公网访问

接口声明：

• app.mysql.openWan(options?): Promise<Object>
• app.mysql.closeWan(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	否	String	实例 ID
InstanceGroupId	否	String	实例组 ID

3. 返回结果

字段	类型	说明
FlowId	Number	任务流 ID
RequestId	String	请求唯一标识

---

describeClusterInstanceGroups

1. 接口描述

接口功能：查询集群的实例组列表（含各实例组的网络信息和实例列表）

接口声明：app.mysql.describeClusterInstanceGroups(): Promise<Object>

2. 返回结果

字段	类型	说明
TotalCount	Number	实例组总数
InstanceGroupInfoList	Array	实例组列表，每项含 Vip/Vport/InstanceSet 等

---

describeInstances

1. 接口描述

接口功能：查询实例列表，支持多维度过滤

接口声明：app.mysql.describeInstances(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Limit	否	Number	返回数量，默认 20，取值 (0,100]
Offset	否	Number	偏移量，默认 0
OrderBy	否	String	排序字段：CREATETIME / PERIODENDTIME
OrderByType	否	String	排序方式：ASC / DESC
Filters	否	IQueryFilter[]	过滤条件，各条件间 AND 关系
Status	否	String	实例状态：creating / running / isolating / isolated 等
InstanceIds	否	String[]	按实例 ID 列表过滤

3. 返回结果

字段	类型	说明
TotalCount	Number	实例总数
InstanceSet	Array	实例详情列表

---

describeInstanceDetail

1. 接口描述

接口功能：查询单个实例的完整详情

接口声明：app.mysql.describeInstanceDetail(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	是	String	实例 ID

3. 返回结果

返回 Detail 对象，包含实例 CPU/内存/存储、网络、状态、版本等全量信息（见 ICynosdbInstanceFullDetail）。

---

restartInstance

1. 接口描述

接口功能：重启指定实例

接口声明：app.mysql.restartInstance(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	是	String	实例 ID

3. 返回结果

字段	类型	说明
FlowId	Number	异步任务流 ID
RequestId	String	请求唯一标识

---

upgradeInstance

1. 接口描述

接口功能：变更实例规格（CPU / 内存）

接口声明：app.mysql.upgradeInstance(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	是	String	实例 ID
Cpu	是	Number	目标 CPU 核数
Memory	是	Number	目标内存（GB）
UpgradeType	是	String	升级时机：upgradeImmediate（立即）/ upgradeInMaintain（维护窗口）
UpgradeMode	否	String	升级模式：NormalUpgrade（普通）/ FastUpgrade（极速）

3. 返回结果

字段	类型	说明
TranId	String	冻结流水 ID
BigDealIds	String[]	大订单号
DealNames	String[]	订单号

---

describeInstanceSlowQueries

1. 接口描述

接口功能：查询实例慢查询日志

接口声明：app.mysql.describeInstanceSlowQueries(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	是	String	实例 ID
StartTime	否	String	起始时间
EndTime	否	String	结束时间
Limit	否	Number	返回数量
Offset	否	Number	偏移量
Username	否	String	按用户名过滤
Host	否	String	按客户端 Host 过滤
Database	否	String	按数据库名过滤
OrderBy	否	String	排序字段：QueryTime / LockTime / RowsExamined / RowsSent
OrderByType	否	String	排序方式：asc / desc
SqlText	否	String	SQL 语句关键字过滤

3. 返回结果

字段	类型	说明
TotalCount	Number	总条数
SlowQueries	Array	慢查询记录列表（含 SQL 语句、耗时、扫描行数等）

---

describeInstanceErrorLogs

1. 接口描述

接口功能：查询实例错误日志

接口声明：app.mysql.describeInstanceErrorLogs(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
InstanceId	是	String	实例 ID
StartTime	否	String	开始时间
EndTime	否	String	结束时间
Limit	否	Number	返回数量
Offset	否	Number	偏移量
OrderBy	否	String	排序字段，支持 Timestamp
OrderByType	否	String	排序方式：ASC / DESC
LogLevels	否	String[]	日志级别：error / warning / note
KeyWords	否	String[]	关键字过滤（模糊搜索）

3. 返回结果

字段	类型	说明
TotalCount	Number	总条数
ErrorLogs	Array	错误日志列表（含 Content/Level/Timestamp）

---

describeClusterDatabases

1. 接口描述

接口功能：查询集群下的数据库列表

接口声明：app.mysql.describeClusterDatabases(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Offset	否	Number	偏移量
Limit	否	Number	返回数量

3. 返回结果

字段	类型	说明
TotalCount	Number	总数
Databases	String[]	数据库名称列表

---

describeClusterDatabaseTables

1. 接口描述

接口功能：查询指定数据库下的表列表

接口声明：app.mysql.describeClusterDatabaseTables(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Db	是	String	数据库名
Offset	否	Number	偏移量
Limit	否	Number	返回数量
TableType	否	String	表类型：view（视图）/ base_table（基本表）/ all（全部，默认）

3. 返回结果

字段	类型	说明
TotalCount	Number	总数
Tables	String[]	表名称列表

4. 示例代码

const { Databases } = await mysql.describeClusterDatabases()
for (const db of Databases) {
  const { Tables } = await mysql.describeClusterDatabaseTables({ Db: db })
  console.log(`${db}: ${Tables.join(', ')}`)
}

---

createAccounts

1. 接口描述

接口功能：批量创建数据库账号

接口声明：app.mysql.createAccounts(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Accounts	是	INewAccount[]	新建账号列表

INewAccount

字段	必填	类型	说明
AccountName	是	String	账号名称
AccountPassword	是	String	密码（8-64位，含大小写字母、数字和符号）
Host	是	String	允许访问的主机（IP 或 %）
Description	否	String	账号描述
MaxUserConnections	否	Number	最大连接数限制

---

deleteAccounts

1. 接口描述

接口功能：批量删除数据库账号

接口声明：app.mysql.deleteAccounts(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Accounts	否	IInputAccount[]	要删除的账号列表（{ AccountName, Host? }）

---

describeAccounts

1. 接口描述

接口功能：查询数据库账号列表

接口声明：app.mysql.describeAccounts(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
AccountNames	否	String[]	按账号名过滤
Hosts	否	String[]	按 Host 过滤
Limit	否	Number	返回数量
Offset	否	Number	偏移量
AccountRegular	否	String	模糊匹配关键字（支持正则）

3. 返回结果

字段	类型	说明
TotalCount	Number	账号总数
AccountSet	Array	账号信息列表（含 AccountName/Host/CreateTime 等）

---

describeAccountPrivileges

1. 接口描述

接口功能：查询账号在指定数据库/表上的权限

接口声明：app.mysql.describeAccountPrivileges(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
AccountName	是	String	账号名
Host	是	String	主机
Db	是	String	数据库名，* 表示全局权限
Type	是	String	对象类型：table（表级）/ *（数据库/全局级）
TableName	否	String	表名（Type='table' 时必填）

3. 返回结果

字段	类型	说明
Privileges	String[]	权限列表

---

describeAccountAllGrantPrivileges

1. 接口描述

接口功能：查询账号所有已授权的权限（全局、数据库、表）

接口声明：app.mysql.describeAccountAllGrantPrivileges(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Account	是	IInputAccount	{ AccountName, Host? }

3. 返回结果

字段	类型	说明
PrivilegeStatements	String[]	权限语句
GlobalPrivileges	String[]	全局权限列表
DatabasePrivileges	Array	数据库权限
TablePrivileges	Array	表权限

---

modifyAccountPrivileges

1. 接口描述

接口功能：修改账号权限

接口声明：app.mysql.modifyAccountPrivileges(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Account	是	IInputAccount	账号信息
GlobalPrivileges	否	String[]	全局权限列表
DatabasePrivileges	否	Array	数据库级权限
TablePrivileges	否	Array	表级权限

---

modifyAccountDescription

接口声明：app.mysql.modifyAccountDescription(options): Promise<Object>

修改账号描述信息。参数：AccountName（必填）、Description（必填）、Host（可选）。

---

modifyAccountHost

接口声明：app.mysql.modifyAccountHost(options): Promise<Object>

修改账号允许访问的 Host。参数：Account（IInputAccount，必填）、NewHost（新 Host，必填）。

---

modifyAccountParams

接口声明：app.mysql.modifyAccountParams(options): Promise<Object>

修改账号配置参数。参数：Account（必填）、AccountParams（IAccountParamItem[]，必填，每项含 ParamName 和 ParamValue）。

---

resetAccountPassword

1. 接口描述

接口功能：重置账号密码

接口声明：app.mysql.resetAccountPassword(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
AccountName	是	String	账号名称
AccountPassword	是	String	新密码
Host	否	String	主机，默认 %

---

createBackup

1. 接口描述

接口功能：手动创建数据库备份

接口声明：app.mysql.createBackup(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
BackupType	否	String	备份类型：logic（逻辑）/ snapshot（物理，默认）
BackupDatabases	否	String[]	指定备份的数据库（仅 logic 类型有效）
BackupTables	否	Array	指定备份的表（仅 logic 类型有效）
BackupName	否	String	备份备注名

3. 返回结果

字段	类型	说明
FlowId	Number	备份任务流 ID

---

deleteBackup

1. 接口描述

接口功能：删除备份文件

接口声明：app.mysql.deleteBackup(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
BackupIds	否	Number[]	备份 ID 列表（推荐）
SnapshotIdList	否	Number[]	快照 ID 列表（旧版，不推荐）

---

modifyBackupConfig

1. 接口描述

接口功能：修改备份策略配置（备份时间窗口、保留时长、备份频率）

接口声明：app.mysql.modifyBackupConfig(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
BackupTimeBeg	否	Number	全备开始时间（秒，如 0=0:00, 3600=1:00）
BackupTimeEnd	否	Number	全备结束时间
ReserveDuration	否	Number	备份保留时长（秒，如七天=604800）
BackupFreq	否	String[]	长度为 7 的数组，对应周一到周日，full/increment
BackupType	否	String	备份类型

---

describeBackupList

1. 接口描述

接口功能：查询备份列表

接口声明：app.mysql.describeBackupList(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
Limit	否	Number	返回数量，取值 (0,100]
Offset	否	Number	偏移量
BackupType	否	String	snapshot（快照）/ logic（逻辑）
BackupMethod	否	String	auto（自动）/ manual（手动）
StartTime	否	String	备份开始时间过滤
EndTime	否	String	备份结束时间过滤
BackupNames	否	String[]	备注名过滤（模糊）

3. 返回结果

字段	类型	说明
TotalCount	Number	总条数
BackupList	Array	备份文件列表（含 BackupId/BackupType/BackupStatus/StartTime/FinishTime 等）

---

describeBackupDownloadUrl

1. 接口描述

接口功能：获取备份文件的下载地址

接口声明：app.mysql.describeBackupDownloadUrl(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
BackupId	是	Number	备份 ID

3. 返回结果

字段	类型	说明
DownloadUrl	String	备份下载地址

4. 示例代码

const { BackupList } = await mysql.describeBackupList({ Limit: 5 })
const latest = BackupList[0]
const { DownloadUrl } = await mysql.describeBackupDownloadUrl({ BackupId: latest.BackupId })
console.log('下载地址:', DownloadUrl)

---

rollBackCluster

1. 接口描述

接口功能：将集群回档到指定时间点或备份文件

接口声明：app.mysql.rollBackCluster(options): Promise<Object>

2. 输入参数

字段	必填	类型	说明
RollbackStrategy	是	String	回档策略：timeRollback（按时间点）/ snapRollback（按备份文件）
RollbackId	否	Number	备份文件 ID（snapRollback 时必填）
ExpectTime	否	String	目标时间点（timeRollback 时必填）
RollbackDatabases	否	Array	回档数据库列表（含 OldDatabase / NewDatabase）
RollbackTables	否	Array	回档表列表（含 Database 及 Tables）
RollbackMode	否	String	时间点回档模式：full（普通）/ db（快速）/ table（极速）

3. 返回结果

字段	类型	说明
FlowId	Number	回档任务流 ID
RequestId	String	请求唯一标识

4. 示例代码

// 按时间点回档（将 users 表回档，写入新表 users_restore）
const { FlowId } = await mysql.rollBackCluster({
  RollbackStrategy: 'timeRollback',
  ExpectTime: '2025-01-01 12:00:00',
  RollbackTables: [{
    Database: 'mydb',
    Tables: [{ OldTable: 'users', NewTable: 'users_restore' }]
  }],
  RollbackMode: 'table'
})
console.log('回档任务流 ID:', FlowId)

---

describeTasks

1. 接口描述

接口功能：查询 MySQL 异步任务列表

接口声明：app.mysql.describeTasks(options?): Promise<Object>

2. 输入参数

字段	必填	类型	说明
StartTimeBegin	否	String	任务开始时间下限
StartTimeEnd	否	String	任务开始时间上限
Filters	否	IQueryFilter[]	过滤条件
Limit	否	Number	返回数量
Offset	否	Number	偏移量

3. 返回结果

字段	类型	说明
TotalCount	Number	总条数
TaskList	Array	任务列表（含 ID/Status/TaskType/StartTime 等）